Zoo Code

지속적으로 관리되는 VS Code 코딩 에이전트를 TokenMix에 연결하세요.

Zoo Code 소개

Zoo Code는 VS Code 안에서 동작하는 AI 코딩 에이전트입니다. 파일 설명, 코드 생성, 리팩터링, 디버깅에 사용할 수 있으며 Code, Architect, Ask, Debug, Custom Modes를 지원합니다. 처음 사용하는 경우에는 먼저 질문하고, 그다음 계획을 받고, 마지막에 작은 파일 수정만 허용하는 방식이 안전합니다.

Zoo Code는 OpenAI Compatible 공급자를 통해 TokenMix에 연결할 수 있습니다. Zoo Code를 직접 배포할 필요는 없습니다. 확장 설정에서 API 주소를 TokenMix로 바꾸면 됩니다.

TokenMix 정보 준비

먼저 다음 값을 준비하세요:

Provider: OpenAI Compatible
Base URL: https://api.tokenmix.ai/v1
API Key: TokenMix API Key
Model: TokenMix model ID, for example <your-model-short-id>

Base URL에는 반드시 /v1이 포함되어야 합니다. OpenAI 기본 주소를 사용하거나 https://api.tokenmix.ai만 입력하지 마세요.

Zoo Code 설치

VS Code를 엽니다.
Extensions를 엽니다.
Zoo Code를 검색합니다.
Extension ID가 ZooCodeOrganization.zoo-code인지 확인합니다.
Install을 클릭합니다.
Zoo Code 패널 또는 command palette에서 Zoo Code settings를 엽니다.

다른 VS Code 코딩 에이전트에서 이동하는 경우에도 먼저 모델 설정만 옮기세요. 채팅과 코드 생성이 정상 작동한 뒤 MCP, 명령 실행 권한, 프로젝트 규칙을 옮기는 것이 좋습니다.

TokenMix API 설정

Zoo Code에서 Settings 또는 Provider settings를 엽니다.
API Provider 또는 Model Provider를 찾습니다.
OpenAI Compatible을 선택합니다.
Base URL에 https://api.tokenmix.ai/v1을 입력합니다.
API Key에 TokenMix Key를 입력합니다.
Model에 TokenMix model ID를 입력합니다.
Reasoning, Responses API, Embedding, Code Index, Context Window 같은 고급 옵션은 처음에는 기본값으로 둡니다.
설정을 저장합니다.

API Key는 보통 VS Code Secret Storage에 저장됩니다. .env, README, 프로젝트 설정 파일, 스크린샷에 Key를 넣지 마세요.

첫 테스트

임시 프로젝트나 테스트 브랜치에서 먼저 시도하세요. 운영 저장소를 바로 수정하게 하지 않는 것이 좋습니다.

Ask mode로 시작합니다:

Explain what the current file does. Do not modify any files.

그다음 Architect mode를 테스트합니다:

Create a plan for a classic frontend-backend separated architecture diagram, including frontend, backend, database, cache, and object storage. Do not modify files.

응답이 정상이라면 작은 Code mode 작업을 테스트합니다:

Create a small TypeScript function that validates an email string and add one simple usage example.

이 3단계가 동작하면 TokenMix Base URL, API Key, Model ID 설정은 대체로 올바릅니다.

권장 사용 순서

Ask: 파일을 수정하지 않고 코드만 설명하게 합니다.
Architect: 구현 전에 계획을 작성하게 합니다.
Code: 범위가 작은 수정만 맡깁니다.
Debug: 명확한 오류 하나를 조사합니다.
Custom Modes: 팀의 반복 작업 방식을 고정합니다.
MCP Servers: 모델 연결이 안정된 뒤 외부 도구를 연결합니다.

IDE 에이전트는 파일을 읽고 쓸 수 있으며 명령을 실행할 수도 있습니다. 처음에는 작은 작업으로 권한 안내를 익힌 뒤 더 큰 작업을 맡기세요.

MCP

Zoo Code는 MCP Servers를 지원합니다. MCP를 사용하면 외부 문서 읽기, 디자인 도구 사용, 읽기 전용 데이터베이스 조회, 내부 서비스 호출 같은 추가 도구를 Agent가 사용할 수 있습니다.

권장 설정 순서:

먼저 TokenMix 모델만 설정합니다.
일반 채팅이 동작하는지 확인합니다.
간단한 MCP Server 하나를 추가합니다.
Agent가 tool list를 볼 수 있는지 확인합니다.
첫 MCP 호출은 읽기 전용 작업으로 테스트합니다.
파일 쓰기, 명령 실행, DB 변경은 별도로 권한을 확인합니다.

처음 설정할 때 모델과 MCP를 동시에 추가하지 마세요. 단계를 나누면 문제가 API, 모델, 권한, MCP 중 어디에 있는지 찾기 쉽습니다.

Code Index와 Embedding

Code Index 또는 저장소 검색을 켜면 embedding 모델 설정이 필요할 수 있습니다.

채팅 모델과 embedding 모델은 따로 설정할 수 있습니다.
UI가 OpenAI Compatible embedding을 지원한다면 TokenMix embedding 모델을 사용할 수 있습니다.
Embedding Base URL도 https://api.tokenmix.ai/v1을 사용합니다.
Model에는 TokenMix embedding model ID를 입력합니다.
dimension이 필요하면 선택한 embedding 모델 설명에 맞춥니다.

처음 사용하는 경우 Code Index를 꺼둬도 괜찮습니다. 일반 채팅, 작은 수정, 코드 설명을 먼저 확인한 뒤 검색 기능을 추가하세요.

문제 해결

401 또는 unauthorized: API Key가 틀렸거나 만료되었거나 앞뒤에 공백이 있습니다.
model not found: TokenMix model ID가 아니거나 계정에 해당 모델 권한이 없습니다.
Base URL error: /v1이 빠졌습니다. https://api.tokenmix.ai/v1을 사용하세요.
요청이 OpenAI로 전송됨: Provider가 OpenAI Compatible이 아니거나 Base URL이 기본값입니다.
출력이 중간에 멈춤: context가 더 큰 모델을 사용하거나 한 번에 보내는 파일 수를 줄이세요.
tool call 거부: Zoo Code 권한 프롬프트와 VS Code workspace trust를 확인하세요.
MCP가 동작하지 않음: 먼저 일반 채팅을 확인한 뒤 MCP Server 실행 상태와 설정 경로를 확인하세요.

초보자 팁

Zoo Code는 코드를 작성할 수 있는 도우미이지만 최종 검토는 사용자가 해야 합니다. 먼저 설명, 다음 계획, 마지막 수정 순서로 사용하세요. 결제, 로그인, 데이터베이스, 운영 설정, 비밀 정보 파일은 특히 조심해야 합니다. 변경 후에는 diff를 확인하고 테스트 또는 build를 실행하세요.