Zoo Code + JoinGonka Gateway: Roo Code에서 Gonka 모델로 이전하기

1단계: 확장 설치. VS Code에서 확장 패널을 열고(Ctrl+Shift+X, macOS는 Cmd+Shift+X) "Zoo Code"를 검색한 뒤 퍼블리셔 Zoo Code Organization의 확장을 설치합니다. 명령 한 줄로도 가능합니다:

code --install-extension ZooCodeOrganization.zoo-code

VS Code 1.100 이상이 필요합니다(확장 매니페스트에 그렇게 명시되어 있습니다). VSCodium, Windsurf 등 Marketplace가 없는 에디터용으로는 확장이 Open VSX에 게시되어 있습니다. 안정 채널(2026년 9월 18일자 3.82.2) 외에 메인 브랜치의 나이틀리인 프리뷰 3.83.x도 있지만, 실사용에는 안정 버전을 선택하세요. 설치 후 활동 표시줄에 Zoo Code 아이콘이 나타납니다.

2단계: 키 발급. gate.joingonka.ai/register에서 가입하고 주소를 인증한 뒤 "API 키" 섹션에서 jg- 접두사가 붙은 키를 만드세요. Zoo Code용으로 별도 키를 만드는 게 좋습니다. 사용량이 통계에서 별도 행으로 보입니다.

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

npx @joingonka/setup --tool zoo --model deepseek

설치 프로그램이 키를 물어봅니다. 명령줄 인자로 전달하지 않는 이유는 셸 기록에 남지 않게 하기 위해서입니다. 기록할 곳도 없습니다. 프로바이더 프로필과 키를 Zoo Code가 파일이 아니라 VS Code의 보호된 시크릿 저장소에 보관하기 때문입니다. 그래서 설치 프로그램은 양식에 넣을 값과 선택한 모델의 실제 한도를 출력합니다:

Zoo Code is configured in the VS Code extension UI (no file is written).
Open the Zoo Code settings (gear icon) → API Provider, then enter:

  API Provider: OpenAI Compatible
  Base URL:     https://gate.joingonka.ai/v1
  API Key:      jg-your-key
  Model:        deepseek-ai/DeepSeek-V4-Flash-0731

Then set the real limits of this model under Model Configuration
(the defaults do not fit any Gonka model):

  Context Window Size: 380000
  Max Output Tokens:   32768
  Image Support:       off

Zoo Code relies on native tool calling only — all our Gonka models support it.

이어서 게이트웨이로 보낸 실제 요청 결과가 나오며, 성공하면 ✓ Verified: the gateway accepted the key, base URL and model.라는 줄이 표시됩니다. 키, URL, 모델은 첫 작업 때가 아니라 즉시 검증됩니다. 출력 블록의 키는 복사하기 쉽도록 전체가 들어 있으니 이 출력을 공개하지 마세요.

--model 플래그를 생략하면 설치 프로그램이 MiniMax M2.7을 넣습니다. 모델을 직접 고르는 상황에서 네트워크에서 용량이 가장 큰 모델을 제안하는 것입니다. Zoo Code에는 DeepSeek V4 Flash로 시작하는 걸 권합니다. 자체 검증에서 도구 결과 이후 턴을 첫 요청에서 완료했습니다. 자세한 내용은 검증 섹션에 있습니다. 플래그는 축약형 glm(GLM-5.3 Flash)과 minimax도 받습니다. --tool 플래그를 생략하면 설치 프로그램이 25개 도구 메뉴를 보여줍니다.

양식의 세부 사항 하나: Zoo Code 3.82.2에는 "Model Configuration"이라는 제목의 별도 블록이 없습니다. 한도 필드는 같은 양식의 아래쪽, "Configure the capabilities and pricing for your custom OpenAI-compatible model"이라는 설명 밑에 있으며, Max Output Tokens가 Context Window Size보다 먼저 옵니다.

Zoo Code를 처음 실행하면 Choose your provider 버튼이 있는 환영 화면이 나타납니다. 이 버튼을 클릭하여 이동한 양식에서 미리 선택된 OpenRouter를 OpenAI Compatible로 변경하고 마지막에 Finish를 누르세요. 나중에 같은 양식을 Zoo Code 패널 헤더의 톱니바퀴 아이콘에 있는 Providers 섹션에서 열 수 있으며, Save 버튼으로 변경 사항을 저장합니다.

네트워크 모델 제한:

나머지 항목은 건드릴 필요 없습니다. Enable streaming과 Include max output tokens는 켜진 상태로 두고, Enable R1 model parameters와 Use Azure는 꺼진 상태로 두세요(이들은 R1 계열 모델 및 Azure OpenAI용 설정입니다). Custom Headers와 Extra Body 필드는 비워두세요.

제한 설정은 모델이 아닌 프로파일에 저장됩니다. 같은 프로파일에서 Model을 변경해도 윈도우와 출력 상한은 그대로 유지됩니다. 따라서 각 모델마다 프로파일을 따로 만드는 것이 편리합니다. 이에 대해서는 다음 섹션에서 다룹니다.

Zoo Code는 Roo Code의 코드베이스에서 파생되었으므로 마이그레이션은 몇 분 내에 완료되며 프로젝트 파일을 건드릴 필요가 없습니다. 공식 마이그레이션 가이드에는 설정 내보내기 및 가져오기 방법이 설명되어 있으며, 나머지는 개별 버튼으로 마이그레이션되거나 이전 경로에서 읽어옵니다:

JoinGonka Gateway를 가리키던 Roo Code 프로필은 주소, 키, 모델 및 제한 설정과 함께 이전됩니다. 모델이 현재 네트워크에서 사용 가능한지 GET https://gate.joingonka.ai/v1/models 목록을 통해 확인하십시오.

모드 및 프로필. 내장 모드는 Code, Debug, Architect(Markdown 파일만 수정), Ask(수정 없이 답변), Orchestrator(다른 모드에 하위 작업 할당) 등 5가지입니다. 입력 필드 옆의 목록, 메시지 시작 부분에 /architect와 같이 모드 이름을 입력하는 명령어, 또는 Ctrl+.(macOS는 Cmd+.) 조합으로 전환할 수 있습니다. 각 모드는 마지막으로 사용한 프로필을 기억하며, 모드를 전환하면 Zoo Code가 자동으로 프로필을 변경합니다.

이로써 모드별로 모델 프로필을 고정하는 편리한 구조를 사용할 수 있습니다. Settings → Providers에서 Configuration Profile 필드 옆의 "+"를 클릭하고 Gonka DeepSeek와 같은 이름을 지정한 후 양식을 작성하십시오. GLM-5.3 Flash와 MiniMax M2.7에 대해서도 반복하십시오(주소와 키는 모두 동일합니다). 그런 다음 각 모드의 입력 필드 옆에 있는 목록에서 프로필을 선택하면 해당 모드가 이를 기억합니다. 목록의 자물쇠 아이콘은 작업 폴더 내의 모든 모드에 하나의 프로필을 고정합니다.

추론 수준. 양식의 Enable Reasoning Effort 체크박스를 켜면 Low, Medium, High, Extra High, Max 목록이 나타납니다. 꺼져 있을 경우 추론 수준은 요청에 포함되지 않습니다. GLM-5.3 Flash의 스위치는 사실상 이진법으로, Low는 추론을 비활성화하고 다른 수준은 완전한 추론을 수행하므로 빠른 질문을 위해 Low가 설정된 별도의 GLM 프로필을 유지하는 것이 좋습니다. 자세한 내용은 GLM-5.3 Flash 개요를 참조하십시오. DeepSeek V4 Flash 및 MiniMax M2.7의 경우 게이트웨이가 척도를 다시 쓰지 않으며, 수준이 어떻게 작동할지는 모델 자체에 달려 있습니다.

분명한 오류가 포함된 작은 파일이 있는 폴더를 여세요. 예를 들어, 덧셈 대신 뺄셈을 하는 함수가 있는 calc.py 파일을 열고, Code 모드에서 "calc.py를 읽고 오류가 있는지 한 문장으로 말해줘"라고 입력하세요. Zoo Code가 파일 읽기 권한을 요청할 것입니다. Auto-Approve 설정에서 미리 허용하지 않은 경우 Approve 및 Deny 버튼이 포함된 "Zoo wants to read this file" 메시지가 뜹니다. 그 후 모델이 완료 도구를 호출하고, 작업은 Task Completed 블록과 함께 응답을 제공하며 종료됩니다. 추론 과정이 있다면 별도의 Thinking 블록에 표시됩니다. 접힌 작업 헤더의 컨텍스트 채우기 비율은 Context Window Size를 기준으로 계산되므로, 이를 정확히 설정해야 하는 또 다른 이유가 됩니다.

이 과정은 Zoo Code의 패턴(플로, 엄격한 스키마 내의 도구, 기록 내 read_file 결과)을 사용하여 재현했습니다. DeepSeek V4 Flash는 attempt_completion 네이티브 호출을 통해 함수가 덧셈 대신 뺄셈을 한다는 올바른 결과를 출력했습니다. 검증의 두 번째 단계는 게이트웨이 대시보드입니다. '사용량(Usage)' 섹션에서 모델별 내역이 표시되고 키의 마지막 요청 시간이 업데이트됩니다.

Auto-Approve가 없는 경우 오류는 API Request Failed 블록으로 나타나며, Retry 및 Start New Task 버튼과 함께 코드 및 재시도까지의 카운트다운이 포함된 Provider Error 헤더가 표시됩니다. 게이트웨이 응답 텍스트는 메시지나 상세 정보에서 확인할 수 있습니다:

에이전트는 일반 채팅과 다르게 토큰을 소비합니다. Zoo Code는 매 요청마다 시스템 프롬프트, 모드 규칙, 도구 설명, 작업 폴더 정보를 포함하므로 질문을 보내기 전부터 수천 토큰이 소비되며, 작업은 보통 여러 단계로 진행됩니다. 따라서 토큰 단가가 매우 중요합니다.

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

Zoo Code의 결제 방식 비교:

Input Price와 Output Price를 입력하면 작업 헤더에 예상 비용이 표시되지만, 1센트 미만의 짧은 작업은 $0.00으로 보일 수 있습니다. 정확한 소비량과 잔액은 대시보드의 "Usage" 및 "Billing" 섹션에서 확인하십시오.

승인 및 자율성. 기본적으로 Auto-Approve는 꺼져 있으며, Zoo Code는 읽기, 쓰기 및 명령 실행 시마다 권한을 요청합니다. 긴 작업을 수행할 때는 입력 필드의 Auto-approve 메뉴에서 필요한 카테고리를 활성화하십시오. 명령 실행을 위해 Destructive Command Guard (Settings → Auto-Approve)가 있습니다. 확장 프로그램이 실행 파일을 다운로드하고, 허용된 명령은 자동으로 실행되며, 차단된 명령은 승인을 기다립니다. Auto-Approve를 사용하면 Zoo Code는 실패한 요청도 자동으로 재시도합니다. 대기 시간은 5초에서 시작하여 시도할 때마다 두 배로 늘어나지만, 최대 10분을 넘지 않습니다.

스트리밍 응답. Enable streaming을 끄지 마십시오. 스트리밍 모드에서 게이트웨이는 생성되는 대로 텍스트를 전달하며 모델의 제한까지만 응답을 제한합니다. 스트리밍 없이 명시적인 제한이 없는 경우, 응답은 1500 토큰에서 잘립니다 (GLM-5.3 Flash의 경우 3000 토큰).

코드 인덱싱. 프로젝트에 대한 의미론적 검색(Codebase Indexing)은 임베딩 공급자를 통해 모델과 별도로 설정됩니다. 로컬 옵션으로 Semble - Local을 사용할 수 있습니다.

이미지. 네트워크 모델은 텍스트 기반입니다. 스크린샷이나 목업 작업을 위해 이미지 처리가 가능한 모델을 사용하는 별도의 프로필을 만들고, 해당 작업 시 전환하여 사용하십시오.

개인정보 보호. Zoo Code는 설치 ID와 연결된 오류 및 사용 데이터를 개발자에게 전송하지만, 코드나 프롬프트는 전송하지 않습니다. 이는 Settings → About Zoo Code의 Allow error and usage reporting 스위치로 끌 수 있습니다. 게이트웨이 측에서는 프롬프트와 응답 내용을 저장하지 않으며, 관리자 페이지에는 요청 및 토큰 카운터만 표시됩니다.