ZCode 설정 튜토리얼: NextHub API 연동

ZCode은 즈푸(Zhipu)가 출시한 에이전트 개발 환경(ADE)입니다. Anthropic / OpenAI 프로토콜을 지원하는 모든 모델 서비스를 커스텀 공급자로 추가할 수 있습니다. NextHub 연동을 마치면 ZCode에서 Claude와 GPT 모델을 바로 사용할 수 있습니다.

연동 단계

1. ZCode 설치

ZCode 공식 사이트에서 Windows / macOS / Linux 설치 파일을 다운로드하여 설치를 완료하세요. 첫 실행 시 표시되는 시작 화면에서 계정 연결은 건너뛰고 바로 메인 화면으로 들어가도 됩니다.

2. 모델 설정 진입

입력창의 모델 이름을 클릭하고 관리 모델을 선택합니다(또는 설정에서 모델 설정 패널로 진입). 그런 뒤 좌측 공급자 목록 하단의 Add Provider 버튼을 클릭하세요.

3. 공급자 정보 입력(Claude 채널)

필드	입력 내용
이름	NextHub
API 프로토콜	Anthropic
인터페이스 주소(Base URL)	https://api.nexthub.cc
API Key	당신의 NextHub ApiKey(Claude 계열 그룹)

Base URL에 /v1을 붙이지 마세요

Anthropic 프로토콜의 인터페이스 주소는 Claude Code의 ANTHROPIC_BASE_URL과 같은 체계입니다. 루트 도메인인 https://api.nexthub.cc만 입력하고, 끝에 /v1을 붙이지 마세요. Messages 인터페이스 경로는 ZCode가 자동으로 붙입니다.

4. 모델 추가 및 활성화

모델 추가 버튼을 클릭하고 이 서비스가 지원하는 모델 ID를 수동으로 입력합니다. 예: claude-opus-5-5, claude-fable-5(전체 목록은 채널과 모델을 참고하고, 모델 광장의 실시간 데이터를 기준으로 하세요). 저장한 뒤 공급자의 활성화 스위치를 켜세요.

5. 검증

대화창으로 돌아가 모델 선택기에서 방금 추가한 모델을 고르고 메시지를 하나 보내세요. 응답이 오면 연동에 성공한 것입니다.

GPT 채널 연동도 가능합니다

공급자를 하나 더 추가합니다. API 프로토콜은 OpenAI를 선택하고, 인터페이스 주소는 https://api.nexthub.cc/v1(/v1 포함)로 입력하며, API Key에는 GPT-Azure(0.47x) 또는 GPT-Pro(0.11x) 그룹의 API 키를 사용하고, 모델 ID에는 gpt-5.6, gpt-6-astra 등을 입력합니다. 두 공급자는 함께 유지할 수 있으며, 모델 선택기에서 언제든지 전환할 수 있습니다.

자주 발생하는 문제

ZCode의 공급자 설정과 터미널 환경 변수는 서로 독립된 두 개의 진입점이며 동기화되지 않습니다. 연결이 계속 로딩 상태로 머물러 있다면 인터페이스 주소에 불필요한 경로가 들어가지 않았는지 먼저 확인하세요. OpenAI 프로토콜에서는 ZCode가 /chat/completions를 자동으로 붙이므로, 주소에 불필요한 경로가 있으면 404가 발생합니다. 모델 ID는 모델 목록과 완전히 일치해야 합니다.