Factory Droid + JoinGonka Gateway: Gonka 네트워크 모델에서의 BYOK

1단계: Droid 설치하기. Factory 문서에 나온 공식 방법은 다음과 같습니다:

# macOS and Linux
curl -fsSL https://app.factory.ai/cli | sh

# Homebrew
brew install --cask droid

# Windows (PowerShell)
irm https://app.factory.ai/cli/windows | iex

# via npm
npm install -g droid

스크립트는 바이너리를 ~/.local/bin에 넣고 이 디렉터리를 PATH에 추가하는 방법을 안내합니다. Linux에서는 문서에서 xdg-utils 패키지도 설치하라고 안내합니다. 확인은 droid --version으로 합니다.

2단계: 키 발급받기. gate.joingonka.ai/register에서 가입하고 주소를 인증한 뒤, «API 키» 섹션에서 jg- 접두사가 붙은 키를 만드세요. 키 하나와 잔액 하나로 네트워크의 모든 모델을 사용할 수 있습니다.

3단계: 설치 프로그램 실행하기.

npx @joingonka/setup --tool droid

설치 프로그램이 키를 물어봅니다. 셸 기록에 남지 않도록 명령줄 인수로는 전달되지 않습니다. 그리고 네 가지 작업을 수행합니다:

• ~/.factory/settings.json(Windows에서는 %USERPROFILE%\.factory\settings.json)의 customModels 배열에 네트워크의 각 모델당 하나씩 항목을 추가합니다: 게이트웨이 주소, 프로바이더 유형 generic-chat-completion-api, 리터럴로 된 키, 실제 컨텍스트 윈도우와 응답 상한. 파일 권한은 600으로 설정됩니다.
• 기본 모델인 sessionDefaultSettings.model을 DeepSeek V4 Flash로 설정합니다. 단, 선택되지 않았거나 네트워크에서 제거된 모델을 가리키는 경우에만 해당합니다. Factory 카탈로그의 모델이나 다른 BYOK 항목은 덮어쓰지 않고 전환 방법만 안내합니다.
• 이전 파일의 사본을 저장하고, customModels의 다른 항목과 나머지 설정, 주석은 그대로 둡니다. 파싱할 수 없는 파일은 덮어쓰지 않고 수정할 부분을 알려줍니다.
• 마지막으로 게이트웨이에 실제 요청을 보내 키, 주소, 모델이 수락되었는지 명확히 알려줍니다.

다른 기본 모델은 --model 플래그로 지정하며, 축약형은 deepseek, glm, minimax입니다. 명시적으로 지정한 모델은 항상 기록됩니다. 닷파일과 서버를 위한 무인 모드도 있으며, 이 모드에서는 환경 변수에서 키를 가져옵니다:

JOINGONKA_API_KEY=jg-your-key npx @joingonka/setup --tool droid --model glm --non-interactive

Droid를 재시작할 필요는 없습니다. settings.json의 변경 사항을 스스로 감지합니다. 마지막에 429 응답과 함께 ! Could not verify right now라는 줄이 나온다면 설정 오류가 아니라 모델이 혼잡한 것이며, 구성은 이미 기록된 상태입니다.

설치 프로그램이 하는 일은 모두 직접 작성할 수 있습니다. Droid의 사용자 설정은 ~/.factory/settings.json에 저장되며, 파일이 없으면 Droid가 첫 실행 시 생성합니다. Gonka 네트워크에는 customModels 배열과 기본 모델이 필요합니다:

{
  "customModels": [
    {
      "model": "deepseek-ai/DeepSeek-V4-Flash-0731",
      "id": "custom:deepseek-ai/DeepSeek-V4-Flash-0731",
      "displayName": "DeepSeek V4 Flash (Gonka)",
      "baseUrl": "https://gate.joingonka.ai/v1",
      "apiKey": "jg-your-key",
      "provider": "generic-chat-completion-api",
      "maxOutputTokens": 32768,
      "maxContextLimit": 380000,
      "noImageSupport": true
    },
    {
      "model": "zai-org/GLM-5.3-Flash",
      "id": "custom:zai-org/GLM-5.3-Flash",
      "displayName": "GLM 5.3 Flash (Gonka)",
      "baseUrl": "https://gate.joingonka.ai/v1",
      "apiKey": "jg-your-key",
      "provider": "generic-chat-completion-api",
      "maxOutputTokens": 8192,
      "maxContextLimit": 390000,
      "noImageSupport": true
    },
    {
      "model": "MiniMaxAI/MiniMax-M2.7",
      "id": "custom:MiniMaxAI/MiniMax-M2.7",
      "displayName": "MiniMax M2.7 (Gonka)",
      "baseUrl": "https://gate.joingonka.ai/v1",
      "apiKey": "jg-your-key",
      "provider": "generic-chat-completion-api",
      "maxOutputTokens": 8192,
      "maxContextLimit": 200000,
      "noImageSupport": true
    }
  ],
  "sessionDefaultSettings": {
    "model": "custom:deepseek-ai/DeepSeek-V4-Flash-0731"
  }
}

기본 모델은 sessionDefaultSettings.model에 저장되며 항목을 id로 참조합니다. Factory 문서에는 파일 루트의 model 키도 언급되어 있지만, 저희 테스트에서 -m 플래그 없이 실행한 droid exec는 sessionDefaultSettings에서 모델을 가져왔고 값을 바꾼 뒤에도 마찬가지였습니다.

키는 파일에 평문으로 저장됩니다. chmod 600 ~/.factory/settings.json으로 파일을 보호하고, 키가 들어간 항목을 프로젝트의 .factory/settings.json으로 옮기지 마세요. 보통 저장소에 커밋되기 때문입니다. 또한 Droid 실행 후 파일 모양이 달라져도 정상입니다. 설정을 저장할 때마다 Droid는 파일 전체를 다시 쓰면서 키를 정렬하고 항목에 index 필드를 추가하며 주석은 저장하지 않습니다. 권한 600은 그대로 유지되고, 설치 프로그램은 이런 항목도 문제없이 갱신합니다.

Droid는 자체 등록 모델을 카탈로그와 별도로 표시합니다. 문서에 따르면 대화형 모드에서 /model 명령이 Custom models 섹션에 이를 출력하고, Ctrl+N은 입력 필드에서 바로 모델을 전환합니다. 일회성 모드에서는 -m 플래그로 모델을 지정하며 값은 id 필드에서 가져옵니다. 슬래시는 그대로 표기합니다: droid exec -m custom:zai-org/GLM-5.3-Flash "…".

이름을 잘못 입력하면 Droid는 Invalid model이라고 응답하며 인식하는 모든 모델을 나열합니다. 자체 모델은 custom:… (display name) 형식으로 표시되므로 등록이 제대로 로드되었는지도 확인할 수 있습니다. Factory 문서 스타일의 이름(레이블과 번호로 구성된 custom:DeepSeek-V4-Flash-(Gonka)-0)은 명시적 id가 있을 때 작동하지 않습니다. 저희 테스트에서도 동일하게 Invalid model이 반환되었습니다.

Factory 계정이 필요한 경우.자체 모델을 사용하면 토큰 결제 문제는 해결되지만, 제품 자체에 로그인해야 하는 문제는 남습니다. 계정 로그인 없이 Droid 0.225.1을 실행한 결과는 다음과 같습니다:

인터페이스에서 작업하려면 Factory 계정을 만들고 브라우저를 통해 로그인하세요. Login 항목 또는 /login 명령을 사용합니다. 브라우저가 없는 머신에서는 문서에서 계정 설정에서 발급한 키를 FACTORY_API_KEY 환경 변수에 설정하는 방법을 제안합니다. 로그인 없이 droid exec를 실행하는 것은 테스트용으로는 편리하지만 공식적으로 문서화되지 않았으므로 CI에서 의존하지 마세요. Factory 요금 페이지에 따르면 BYOK는 무료 한도가 포함된 모든 개인 요금제에 포함되며, 한도를 초과한 BYOK 사용은 요금제 조건에 따라 청구됩니다. 최신 조건은 factory.ai/pricing에서 확인하세요. 네트워크 모델의 토큰은 별도로 JoinGonka 잔액에서 결제됩니다.

어떤 모델을 선택할까.네트워크의 모든 모델 가격은 동일하므로 선택 기준은 동작입니다. 하나의 작업(파일을 읽고 오류를 찾기)으로 droid exec를 실행한 결과는 다음과 같습니다:

-r 플래그(추론 수준)는 Factory 문서에 따르면 BYOK 모델에는 적용되지 않습니다. 기본값으로 DeepSeek V4 Flash가 선택된 이유는 모델 리뷰에서 다룹니다.

빈 디렉터리에 명백한 버그가 있는 calc.py 파일을 넣으세요. 예를 들어 직사각형의 넓이를 구할 때 변의 길이를 곱하지 않고 더하는 코드를 넣고, Droid에게 버그를 찾아달라고 요청하세요:

droid exec "Read the file calc.py in the current project directory and tell me in one sentence whether it has a bug."

플래그 없이 droid exec는 읽기 전용 모드로 작동합니다. 파일을 볼 수는 있지만 변경할 수는 없습니다. 에이전트가 스스로 읽기 도구를 호출하여 잘못된 표현을 명시하며 핵심을 답변합니다. -o json 플래그를 사용하면 응답이 단일 객체로 반환되어 스크립트로 파싱하기 편리합니다(출력은 생략됨):

{"type":"result","subtype":"success","is_error":false,"duration_ms":2239,"num_turns":2,
 "result":"Yes, the file has a bug: the rectangle area is computed as the sum of the side lengths, but it should be their product (width * height). …",
 "usage":{"input_tokens":19016,"output_tokens":146,"factory_credits":0,"ttft_ms":747}}

factory_credits: 0 필드는 작업이 Factory 크레딧이 아닌 사용자의 모델에서 실행되었음을 확인해 줍니다. 에이전트가 파일을 수정할 수 있게 하려면 자율성 수준을 추가하세요: droid exec --auto low "Fix the bug in calc.py and change nothing else." — 저희 테스트에서 DeepSeek V4 Flash는 파일을 읽고, 덧셈을 곱셈으로 바꾸고, 12가 출력되는지 확인하기 위해 스스로 스크립트를 실행했습니다.

세 번째 확인은 게이트웨이 측에서 이루어집니다: 관리 화면의 '사용량' 섹션에서 요청이 '모델별' 내역에 나타나고, '키별' 블록에서 마지막 요청 시간이 갱신됩니다.

문제가 발생했다면 Droid의 특성을 알아두세요: 콘솔에서 droid exec는 Error during droid execution: Exec failed만 출력하고(JSON에서는 "result":"Exec failed"), 실제 원인은 로그에 남습니다. 다음 명령어 하나로 확인할 수 있습니다:

grep agent_error_count ~/.factory/logs/droid-log-single.log | grep -o '"errorMessage":"[^,]*' | tail -1

에이전트 도구는 채팅과는 다른 방식으로 토큰을 소비합니다. Droid는 사용자의 각 구문마다 시스템 프롬프트, 도구 설명, 작업 디렉토리의 스냅샷을 추가하기 때문에 하나의 작업이 여러 턴을 소요하게 됩니다. 저희의 테스트 결과, 각 턴은 질문이 전달되기 전부터 이미 약 9,500개의 입력 토큰을 생성했습니다. 「파일을 읽고 오류 찾기」 작업은 2턴(약 1만 9천 토큰), 「수정 및 검증」은 4턴(약 4만 4천 토큰)이 소요되었습니다. 따라서 이곳에서는 토큰 단가가 매우 중요합니다.

JoinGonka Gateway를 통하면 토큰 비용은 입력 100만 토큰당 $0.0069, 출력 100만 토큰당 $0.021입니다. 이 가격은 네트워크의 모든 모델에 동일하게 적용되며, 이 페이지의 실시간 소스에서 동적으로 불러옵니다.

우측 열의 수치는 2026년 9월 가격 기준입니다. 참고로 Droid에서 모델 비용을 지불하는 방법은 다음과 같습니다:

Droid 인터페이스의 /cost 명령어를 통해 세션 통계를 확인할 수 있으며, BYOK 모델의 정확한 소비량과 잔액은 게이트웨이 관리 페이지의 「사용량(Usage)」 및 「결제(Billing)」 섹션에서 확인할 수 있습니다. Droid용 키를 별도로 생성하면 트래픽을 개별 행으로 구분하여 볼 수 있습니다.

자율성. 일회성 모드에서 Droid는 기본적으로 읽기만 하며, 권한은 수준에 따라 확장됩니다: --auto low — 파일 수정, --auto medium — 추가로 의존성 설치, 빌드, 테스트, 로컬 커밋, --auto high — push와 배포까지. --skip-permissions-unsafe 플래그는 모든 검사를 해제합니다 — 일회용 컨테이너 전용입니다. 대화형 모드에서는 Ctrl+L로 수준을 전환하고, 시작 수준은 sessionDefaultSettings.autonomyLevel로 설정합니다. 기본값은 off입니다 — 모든 것이 확인을 거칩니다.

커밋 서명. includeCoAuthoredByDroid 설정은 기본적으로 활성화되어 있습니다: Droid가 커밋 메시지에 공동 작성자 줄을 추가합니다. 필요 없다면 settings.json에 "includeCoAuthoredByDroid": false를 입력하세요.

세션 저장 위치. 계정에 로그인하면 Droid는 기본적으로 CLI 세션을 Factory 웹 버전에 미러링합니다 — 이는 cloudSessionSync가 담당합니다. BYOK 키는 문서에 따르면 로컬에 남습니다. 대화 내용도 컴퓨터에 남기고 싶다면 "cloudSessionSync": false로 설정하세요. 게이트웨이는 프롬프트와 응답 내용을 저장하지 않습니다 — 통계에는 사용량 집계만 남습니다.

업데이트. 스크립트로 설치한 경우 자동으로 업데이트됩니다. 버전을 고정하려면 FACTORY_DROID_AUTO_UPDATE_ENABLED=false 변수나 droid update --version <version> 명령을 사용하세요. npm에서 설치한 빌드는 자동으로 업데이트되지 않습니다. 업데이트 후 droid exec 한 번으로 네트워크 모델이 제대로 있는지 확인하세요.

이미지. 네트워크 모델은 텍스트 기반입니다. 스크린샷용으로는 비전 기능이 있는 모델 항목을 다른 프로바이더에 준비해 두세요.

벤더 계정 없이 작업하는 것이 필수라면. 동일한 네트워크 모델을 로그인이 필요 없는 오픈 터미널 에이전트에도 연결할 수 있습니다 — 예를 들어 OpenCode에 동일한 설치 프로그램으로 --tool opencode 플래그를 사용해 연결합니다.