Настройка пользовательского API ZCode AI

ZCode может добавлять службы, реализующие протокол Anthropic или OpenAI, в качестве пользовательских поставщиков. Это руководство соответствует фактическому порядку в официальном потоке Connect Models → Custom Providers (Anthropic / OpenAI Compatible) ZCode и настраивает TokenHub в качестве поставщика OpenAI-compatible в https://us-api.tokenhub.com/v1.

Открыть настройки модели

При первом запуске, когда ни одна модель недоступна, выберите Use API Key. Если ZCode уже открыт, щелкните название модели в окне подсказки, выберите Manage Models и откройте Settings → Model Settings.

Добавьте пользовательский поставщик TokenHub.

Выполните семь шагов в потоке пользовательского поставщика ZCode:

1. Откройте Settings → Model Settings.
2. Внизу списка поставщиков нажмите Add Provider.
3. Назовите поставщика TokenHub.
4. Выберите OpenAI-compatible. В меню «Базовый URL» выберите собственный адрес или введите https://us-api.tokenhub.com/v1 вручную.
5. Введите свой ключ TokenHub API в API Key.
6. Нажмите Add Model и введите точный идентификатор модели из каталога моделей TokenHub. Добавляйте каждую дополнительную модель отдельно.
7. Сохраняем настройки и включаем провайдерский переключатель Enable. Убедитесь, что каждая модель, которую вы собираетесь использовать, также включена.

ZCode не определяет для вас идентификаторы сторонних моделей. Если поставщик не возвращает список моделей, добавьте каждый точный идентификатор вручную с помощью Add Model.

Не смешивайте настройки протоколов 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 объединяет поставщика, идентификатор модели, возможности каталога моделей и активный протокол при обработке изображений:

• Когда поддержка известна, ZCode сохраняет изображение и отправляет его в службу модели.
• Если модель помечена как неподдерживаемая, ZCode удаляет изображение и заменяет его текстовым уведомлением.
• Если возможности неизвестны, ZCode не блокирует изображение заранее; TokenHub принимает окончательное решение и может отклонить запрос.

Одна и та же модель может обрабатываться по-разному через другого поставщика или протокол. Сначала проверьте текст и отправьте изображение только в том случае, если на странице модели TokenHub явно указаны входные изображения.

Выберите модель и проверьте

1. Вернитесь к средству выбора модели в окне подсказки.
2. Выберите поставщика TokenHub и добавленную вами модель.
3. Отправьте короткую инструкцию, например «Объясните текущий файл, не изменяя его».
4. В журналах запросов TokenHub подтвердите, что запрос использует /v1/chat/completions, и проверьте идентификатор модели, код состояния и использование.
5. После того как текстовые ответы стабилизируются, проверьте редактирование, вызовы инструментов, длинный контекст и ввод изображений отдельно.

Это соответствует официальному руководству ZCode Verify The Setup: выберите новый канал, отправьте короткую тестовую инструкцию и подтвердите стабильный ответ перед реальной работой.

Область применения встроенного прокси HTTP ZCode

Прокси-сервер HTTP, настроенный в ZCode Settings, охватывает API модели, MCP, WebFetch, дочерние процессы терминала, рынок расширений и загрузку страниц в приложении. Он не охватывает вход в учетную запись настольного компьютера, создание Wiki, веб-удаленный контроль WebSocket или удаленные подключения SSH. ZCode также по умолчанию не маршрутизирует каждый запрос через системные переменные HTTP_PROXY/HTTPS_PROXY. Перезапустите ZCode после изменения прокси-сервера в приложении.

Устранение неполадок

• Модель отсутствует: убедитесь, что и поставщик, и модель включены.
• 404: подтвердите, что конечная точка не повторяет /chat/completions.
• Несоответствие формата запроса: проверьте, является ли провайдер OpenAI-compatible или Anthropic.
• Текст работает, а редактирование кода — нет: выбранная модель может не иметь надежного встроенного вызова инструментов.
• Усилие мышления возвращает 400: понизьте или отключите уровень, поскольку развертывание может его не принять.
• Запрос изображения не выполнен: используйте канонический идентификатор модели и подтвердите, что поставщик, протокол и модель TokenHub поддерживают все изображения.
• Изменение прокси-сервера не имеет никакого эффекта: перезапустите ZCode и убедитесь, что тип трафика покрывается встроенным прокси-сервером ZCode.

Официальная ссылка

• ZCode: Подключаемые модели