ZCode는 최초 실행 시 내장 프로바이더(Provider)가 선택된 상태로 시작됩니다. 이 상태만으로도 대화는 가능하지만, 여러 모델을 한 번에 처리할 수 있는 게이트웨이(Gateway) 키를 가지고 있다면 내장 카드로는 연결할 수 없습니다. 이는 주소(Address), 프로토콜(Protocol), 모델 목록이 카드 측에서 고정되어 있기 때문입니다.
본 기사는 커스텀 프로바이더(Custom Provider)를 생성하여 자체 키로 구동하는 절차를, 실제로 화면을 조작한 순서대로 정리했습니다. 입력해야 하는 항목은 4가지뿐이며, 나머지는 UI 조작에 해당합니다.
| 항목 | 값 |
|---|
| OS | Windows 11 |
| ... | |
| ZCode 데스크톱 버전은 공식 웹사이트(https://zcode.z.ai/)에서 Windows, macOS, Linux용으로 배포되고 있습니다. 본 기사의 화면은 모두 Windows 버전을 기준으로 합니다. | |
커스텀 프로바이더의 폼에는 6가지 항목이 있지만, 실질적으로 효력이 있는 것은 다음 4가지입니다.
- Base URL: 게이트웨이의 루트 주소(Root Address). 도메인까지만 지정합니다. -
- API 형식:
/v1/messages를 포함하는 항목을 선택합니다. -
- API 키: 콘솔에서 발급한 토큰입니다. 로그인 비밀번호가 아닙니다. -
- 모델 목록: 모델 ID를 복사하여 추가합니다.
이름(Name)과 활성화 스위치(Enable Switch)는 표시 및 ON/OFF 용도일 뿐입니다.
인스톨러를 실행하고 시작 메뉴에서 구동합니다. 최초 실행 시 2개의 화면을 거칩니다.
첫 번째 화면은 '주요 작업 방향'을 12가지 선택지 중 하나를 고르는 것인데, 이는 클라이언트의 제안 방식이 바뀔 뿐 외부 프로바이더 연결 가능 여부에는 영향을 주지 않습니다. 왼쪽 하단의 '건너뛰기(Skip)'로 진행할 수 있습니다.
두 번째 화면은 계정 연결(Account Connection) 단계이며, 프로바이더 드롭다운 메뉴는 내장 서비스를 가리키고 그 아래에 API 키 입력란이 있습니다. 여기에 넣는 것은 내장 서비스의 키이므로, 이번에는 사용하지 않습니다. 하단의 '나중에 건너뛰기(暂时跳过)'로 닫습니다.
두 단계 모두 설정(Setting)이 아니라 온보딩(Onboarding) 과정입니다. 나중에 같은 설정 화면에서 프로바이더를 추가할 수 있으므로, 돌아와서 다시 채울 필요는 없습니다.
콘솔에 로그인하여 토큰 관리 화면에서 새로 생성합니다. 이름은 zcode처럼 식별하기 쉬운 것이면 됩니다. 생성 직후 한 번만 전체 내용이 표시되는 구현이 많으므로, 그 자리에서 복사해야 합니다.
권한(Permission), 잔액(Balance), 유효 기간(Expiration Date) 등은 콘솔 측의 정보입니다. 클라이언트는 키를 요청에 포함하기만 하므로, 사용할 예정인 모델에 대한 권한이 있는지 미리 확인해 둡니다. 이번 예시에서는 Crazyrouter의 콘솔을 사용했습니다. 과금은 종량제(Pay-as-you-go)이며, 충전이나 캠페인 내용은 콘솔 표시가 기준입니다.
설정을 열면 왼쪽 부분이 '기본 설정(Basic Settings)'과 'Agent 기능(Agent Function)' 두 그룹으로 나뉘어 있습니다. 기본 설정 아래에 '일반', '외관', '모델 설정(Model Setting)', '브라우저 제어' 등이 나열되므로, 모델 설정을 선택합니다.
오른쪽 상단의 '새 공급자 추가(新增供应商)'를 누르면 패널이 열리며, 윗부분은 내장 카드이고 아랫부분의 '기타(其他)'에 일반적인 벤더들이 나열됩니다. 그 맨 앞이 '커스텀 공급자 생성(创建自定义供应商)'입니다.
내장 카드와의 차이는 연결 파라미터를 누가 가지고 있느냐뿐입니다. 카드는 주소와 프로토콜이 고정되어 있지만, 커스텀은 둘 다 직접 입력합니다. 게이트웨이나 자체 엔드포인트는 이 방법을 사용합니다. 한 번 만든 프로바이더는 왼쪽에 남아 있으므로, 이름을 클릭하면 편집할 수 있습니다.
폼은 '이름', '활성화 스위치', 'Base URL', 'API 형식', 'API 키', '모델 목록'의 6가지 항목으로 구성되어 있습니다.
**이름(Name)**은 기본값인 '새 공급자' 상태로는 목록에서 구별하기 어려우므로, '팀 네트워크 게이트웨이'와 같이 이름 변경을 해둡니다.
Base URL은 도메인까지만 지정합니다. 이번 값은 다음과 같습니다.
끝에 /v1이나 /messages 등을 붙여서는 안 됩니다. 주소(Address)와 프로토콜(Protocol)은 별도의 항목이며, 경로는 아래의 형식 선택이 결정합니다. 직접 경로를 추가하면 404 에러가 발생하기 쉬운 전형적인 패턴입니다.
API 형식은 /v1/messages를 포함하는 항목을 고릅니다. 이 한 항목이 요청의 경로와 응답 해석 방법 양쪽을 결정하므로, 게이트웨이가 실제로 열려 있는 프로토콜과 일치시켜야 합니다. 잘못하면 400 또는 404가 발생하며 인증 오류는 아닙니다. 또한 /v1/messages와 /v1/chat/completions는 다른 페이로드 형식(Payload Format)을 가지므로, 주소가 정확해도 형식이 다르면 통과할 수 없습니다.
API 키는 절차 2에서 복사한 토큰입니다. 입력란 오른쪽의 눈 아이콘으로 확인하고, 앞뒤에 공백이 있거나 끝 부분이 누락되면 401 오류가 발생합니다. 키는 로컬 설정에 저장되므로 채팅창이나 스크린샷에 붙여넣지 않도록 합니다.
모델 목록은 '➕ 모델 추가'를 눌러 ID를 입력합니다. 처음에는 하나만 있어도 충분합니다. 각 행마다 스위치와 삭제 버튼이 있으며, 비활성화한 모델은 대화 선택 목록에 나타나지 않습니다.
입력 후, 패널 상단의 활성화 스위치가 켜져 있는지 확인합니다. 저장하지 않고 닫으면 입력 내용이 사라집니다.
모델 ID는 직접 타이핑하지 말고 콘솔의 모델 목록에서 복사해야 합니다. 검색창에 'glm'을 입력하면 필터링되며, 스크린샷에서는 170개 항목 중 10개가 표시되어 있습니다. 각 카드 오른쪽 상단 'Details' 옆 아이콘에서 ID를 복사하여 양식에 붙여넣습니다. 대소문자는 변경하지 않습니다.
같은 프로바이더에 여러 모델을 연결할 수 있습니다. 주소와 키는 공통이고, 다른 것은 ID뿐입니다. 주소와 키가 게이트웨이를 결정하고, ID가 그 안의 특정 모델을 결정하는 역할 분담이므로, 모델을 늘려도 인증 정보를 다시 입력할 필요가 없습니다.
저장한 후 새로운 대화를 열고, 모델 선택에서 프로바이더 그룹을 고른 다음 모델을 선택합니다. 짧은 지시를 보내고 응답이 있다면 연결된 것입니다. 입력란 오른쪽 아래에 현재 모델명이 표시되며, 그 옆의 문자가 사고 강도(思考強度) 단계입니다.
여기서 한 번 실수하기 쉬운 부분이, 설정은 완료되었는데 대화가 이전 프로바이더 상태로 남아있는 경우입니다. 이미 열려 있는 대화는 새로운 프로바이더로 자동 전환되지 않습니다. 대화 하단의 모델 선택에서 그룹을 수동으로 전환해야 합니다.
glm 계열은 이름이 규칙적입니다. 버전 번호 뒤에 접미사가 붙는데, flash는 저비용(low cost), flashx는 그 고속 버전, v는 시각 처리(visual), ocr는 문서 분석(document analysis), legal은 법무 전용입니다.
| 모델 | 위치/특징 | 컨텍스트 / 출력 | 주요 용도 |
|---|
| glm-5.3 | 플래그십 (Flagship) | 1M / 128K | 프로젝트 전체 개수, 긴 디버깅 |
| ... | | | |
glm-5.1, glm-5, glm-5-turbo, glm-3-turbo는 구세대 모델입니다. 기존 처리가 의존하고 있지 않다면 5.3 계열부터 선택하는 것이 안전합니다. 참고로 glm-5.3은 항상 사고(思考) 기능이 활성화되어 있으며, low・high・max의 3단계가 있습니다. 간단한 질문에는 low가, 무거운 수정 작업에는 max가 적합합니다. | | | |
주소에 경로 추가하기: /v1이나 /messages를 쓰면 404 오류가 납니다. 경로는 형식 선택이 담당합니다.
형식 오인: 400 또는 404로 나타나 인증 오류처럼 보이지 않습니다. 주소가 아니라 형식을 의심해야 합니다.
키 앞뒤 공백: 401 오류가 나며, 키가 다른 경우와 구별하기 어렵습니다.
저장 누락: 양식을 닫기 전에 저장하지 않으면 프로바이더 자체가 생성되지 않습니다.
그룹 미전환: 설정이 올바르더라도 열려 있는 대화는 이전 프로바이더 상태로 남아있습니다.
필요한 입력은 Base URL, API 형식(format), API 키, 모델 ID의 네 가지입니다. 주소는 도메인까지, 형식은 /v1/messages, 키는 콘솔 토큰, ID는 복사합니다. 이 네 가지만 숙지하면, 이후에는 대화 측에서 그룹을 전환하는 것만으로 작동시킬 수 있습니다.
설정과 대화가 별개라는 점, 그리고 전환해도 오류 메시지가 뜨지 않는다는 점이 이 절차에서 유일하게 이해하기 어려운 부분입니다. 오류의 유무로 판단하기보다는 입력란 오른쪽 아래 모델명으로 판단하는 것이 가장 확실합니다.
