ZCode 사용자 지정 모델: Claude와 GPT

ZCode는 즈푸(Zhipu)의 데스크톱 coding agent입니다. 하나의 OpenAI 호환 공급자를 Code By AI로 향하게 하면 Claude와 GPT 모델을 실행할 수 있습니다.

ZCode는 단순한 터미널 래퍼가 아닌 Agentic Development Environment입니다. Agent가 채팅에서 파일, 터미널, Git, 브라우저 미리보기를 직접 다룹니다. Model Settings 패널이 사용자 지정 공급자를 받으므로 모델 연결만 바꾸면 됩니다.

명령 하나로 설정 (macOS / Linux)

먼저 ZCode를 완전히 종료하세요. ZCode는 공급자 목록을 메모리에 유지하고 저장하거나 종료할 때 ~/.zcode/v2/config.json을 다시 쓰므로, 실행 중에 편집한 내용은 사라집니다.

Copy
1
curl -fsSL https://www.codebyai.net/setup.sh | sh -s -- --zcode

스크립트는 API 키를 숨김 입력으로 물어본 뒤 codebyai 공급자와 gpt-5.6-terra, claude-sonnet-5 모델을 추가하고, 원본 파일을 백업하며 소유자만 읽고 쓸 수 있게 합니다. 다시 실행하면 키가 갱신되고, | sh -s -- --uninstall은 원래 파일을 복원합니다. 아래 수동 단계도 같은 작업을 합니다.

1. Code By AI API 키 만들기

Code By AI에 로그인하고 API Keys 페이지에서 키를 만듭니다. sk-proj-... 형식입니다.

2. 모델 설정 열기

ZCode 채팅 입력창 아래의 모델 선택기를 열고 Manage models를 클릭합니다. Settings → Model Settings가 열리고, 여기서 공급자를 추가합니다.

3. 공급자 추가하기

1. 왼쪽 공급자 목록 하단의 Add Provider를 클릭합니다.
2. 이름을 Code By AI로 지정합니다.
3. OpenAI API base URL에 https://www.codebyai.net/api/agent/v1을 설정합니다.
4. Code By AI API 키를 붙여 넣습니다.
5. 저장한 뒤 Add Model을 클릭하고 gpt-5.6-terra를 입력합니다. Add Model을 한 번 더 클릭해 claude-sonnet-5를 추가합니다.
6. 공급자의 활성화 스위치를 켭니다.

두 모델 패밀리 모두 OpenAI 프로토콜을 사용합니다. ZCode의 Anthropic-messages 모드는 구식 thinking 파라미터를 보내 현재 Claude 모델이 거부합니다. 게이트웨이의 Chat Completions 경로는 claude-* ID를 Claude 채널로 전달하고 Claude 요금으로 과금하므로, 공급자 하나로 두 패밀리를 모두 처리합니다.

4. 모델 선택 및 테스트

세션을 열고 모델 선택기에서 둘 중 하나를 고른 뒤 짧은 질문을 보냅니다. 정상 응답이 오면 엔드포인트, 키, 모델 ID가 모두 맞습니다.

모델 ID와 컨텍스트 윈도

모델 ID는 Model Plaza에 나온 값을 사용하세요. 위의 두 개는 이 가이드를 작성할 당시의 예시입니다. 사용자 지정 공급자에 추가한 모델은 ZCode에서 200,000 토큰 컨텍스트 윈도로 시작합니다. Settings → Model Providers → Advanced에서 모델을 열면 윈도와 최대 출력 토큰을 바꿀 수 있습니다. 두 값 모두 저장 후 새 세션부터 적용됩니다.

문제 해결

• 404 page not found — base URL이 불완전하거나 경로가 더 붙어 있습니다. https://www.codebyai.net/api/agent/v1을 쓰고, /chat/completions를 덧붙이거나 /v1을 중복하지 마세요.
• 401 / 잘못된 키 — 키 앞뒤에 공백이 있거나 삭제·만료되었습니다. API Keys 페이지에서 새 키를 만들어 다시 붙여 넣으세요.
• 잔액 부족 — Wallet 페이지에서 충전하세요.
• 400에 reasoning level이 언급됨 — 사용자 지정 공급자가 ZCode의 최고 사고 수준을 거부할 수 있습니다. 해당 모델의 effort를 낮추세요. 게이트웨이는 ZCode가 보낸 수준을 그대로 전달합니다.
• 공급자의 모델 목록이 비어 있음 — 활성화 스위치가 꺼져 있거나 Add Model이 저장되지 않았습니다.
• ZCode를 다시 시작하면 공급자가 사라짐 — 스크립트가 파일을 쓸 때 앱이 실행 중이었습니다. 완전히 종료한 뒤 명령을 다시 실행하고, 그 다음에 앱을 여세요.