ZCode AI 맞춤형 API 설정

ZCode는 Anthropic 또는 OpenAI 프로토콜을 사용자 정의 공급자로 구현하는 서비스를 추가할 수 있습니다. 이 가이드는 ZCode의 공식 Connect Models → Custom Providers (Anthropic / OpenAI Compatible) 흐름의 실제 순서를 따르며 https://us-api.tokenhub.com/v1에서 TokenHub를 OpenAI-compatible 공급자로 구성합니다.

모델 설정 열기

처음 실행 시 모델이 없으면 Use API Key를 선택하세요. ZCode가 이미 열려 있는 경우 프롬프트 상자에서 모델 이름을 클릭하고 Manage Models를 선택한 다음 Settings → Model Settings를 엽니다.

TokenHub 사용자 정의 공급자 추가

ZCode 사용자 지정 공급자 흐름의 7단계를 따르세요.

1. Settings → Model Settings를 엽니다.
2. 공급자 목록 하단에서 Add Provider를 클릭합니다.
3. 공급자 이름을 TokenHub로 지정합니다.
4. OpenAI-compatible를 선택합니다. Base URL 메뉴에서 사용자 정의 주소를 선택하거나 https://us-api.tokenhub.com/v1를 수동으로 입력합니다.
5. API Key에 TokenHub API 키를 입력하세요.
6. Add Model를 클릭하고 TokenHub 모델 카탈로그에서 정확한 모델 ID를 입력하세요. 각 추가 모델을 별도로 추가합니다.
7. 설정을 저장하고 공급자의 Enable 스위치를 켜십시오. 사용하려는 모든 모델도 활성화되어 있는지 확인하십시오.

ZCode는 타사 모델 ID를 추론하지 않습니다. 공급자가 모델 목록을 반환하지 않는 경우 Add Model를 사용하여 각 정확한 ID를 수동으로 추가하세요.

하나의 공급자에 Anthropic 및 OpenAI 프로토콜 설정을 혼합하지 마십시오. Anthropic Messages에 대한 별도의 공급자를 만들고 해당 프로토콜에 필요한 루트 URL를 사용합니다.

한 모델에 대한 고급 설정 구성

Settings → Model Providers에서 추가한 모델을 열고 Advanced를 확장합니다.

• **Max output tokens:**는 일반적으로 이 값을 비워 두고 모델 서비스가 지원되는 값을 보고하도록 합니다. 대상 모델의 제한을 확인한 후 수동으로 설정하십시오.
• Context window: 이는 사용자 정의 공급자 모델에 대해 편집 가능하며 저장된 값은 새 대화에만 적용됩니다. 다른 모델의 값이 아닌 TokenHub 모델 사양을 사용하십시오.
• Thinking effort: 표시 수준은 모델 및 프로토콜에 따라 다릅니다. OpenAI-compatible 요청은 reasoning_effort를 사용합니다. 타사 배포에서는 ZCode에 표시된 일부 수준을 거부할 수 있습니다. 400 매개변수 오류가 발생하면 수준을 낮추거나 옵션을 비활성화하세요.
• Custom request parameters: ZCode는 로컬 공급자 options에 수동으로 추가된 임의의 값을 요청 본문에 자동으로 삽입하지 않습니다. 추가적인 추론이나 이미지 매개변수를 추가하기 위해 ~/.zcode/v2/config.json 편집에 의존하지 마십시오.

ZCode가 이미지 입력 가능 여부를 결정하는 방법

ZCode는 이미지를 처리할 때 공급자, 모델 ID, 모델 카탈로그 기능 및 활성 프로토콜을 결합합니다.

• 지원이 알려지면 ZCode는 이미지를 보관하고 모델 서비스로 보냅니다.
• 모델이 지원되지 않는 것으로 표시되면 ZCode는 이미지를 제거하고 텍스트 알림으로 대체합니다.
• 기능을 알 수 없는 경우 ZCode는 이미지를 미리 차단하지 않습니다. TokenHub가 최종 결정을 내리고 요청을 거부할 수 있습니다.

동일한 모델이 다른 공급자나 프로토콜을 통해 다르게 취급될 수 있습니다. 먼저 텍스트를 테스트하고 TokenHub 모델 페이지에 이미지 입력이 명시적으로 나열되어 있는 경우에만 이미지를 보냅니다.

모델을 선택하고 확인하세요.

1. 프롬프트 상자의 모델 선택기로 돌아갑니다.
2. TokenHub 공급자와 추가한 모델을 선택합니다.
3. "현재 파일을 수정하지 않고 설명하세요."와 같은 간단한 지시를 보냅니다.
4. TokenHub 요청 로그에서 요청이 /v1/chat/completions를 사용하는지 확인하고 모델 ID, 상태 코드 및 사용법을 확인합니다.
5. 텍스트 응답이 안정되면 편집, 도구 호출, 긴 컨텍스트, 이미지 입력을 별도로 테스트합니다.

이는 ZCode의 공식 Verify The Setup 지침을 따릅니다. 즉, 새 채널을 선택하고, 짧은 테스트 지침을 보내고, 실제 작업 전에 안정적인 응답을 확인합니다.

ZCode의 내장 HTTP 프록시 범위

ZCode Settings에 구성된 HTTP 프록시는 모델 API, MCP, WebFetch, 터미널 하위 프로세스, 확장 마켓플레이스 및 인앱 페이지 로딩을 다룹니다. 데스크톱 계정 로그인, Wiki 생성, 웹 원격 제어 WebSocket 또는 SSH 원격 연결은 다루지 않습니다. 또한 ZCode는 ​​기본적으로 시스템 HTTP_PROXY / HTTPS_PROXY 변수를 통해 모든 요청을 라우팅하지 않습니다. 인앱 프록시를 변경한 후 ZCode를 다시 시작하세요.

문제 해결

• 모델 누락: 공급자와 모델이 모두 활성화되어 있는지 확인하세요.
• 404: 엔드포인트가 /chat/completions를 반복하지 않는지 확인합니다.
• 요청 형식 불일치: 공급자가 OpenAI-compatible인지 또는 Anthropic인지 확인하세요.
• 텍스트는 작동하지만 코드 편집은 작동하지 않습니다. 선택한 모델에 안정적인 기본 도구 호출이 없을 수 있습니다.
• 생각에 노력하면 400이 반환됩니다. 배포에서 이를 허용하지 않을 수 있으므로 수준을 낮추거나 비활성화합니다.
• 이미지 요청 실패: 정식 모델 ID를 사용하고 공급자, 프로토콜 및 TokenHub 모델이 모두 이미지를 지원하는지 확인하세요.
• 프록시 변경 사항이 적용되지 않습니다. ZCode를 다시 시작하고 트래픽 유형이 ZCode의 내장 프록시에 포함되는지 확인하세요.

공식 참고자료

• ZCode: 모델 연결