LibreChat: кастомный эндпоинт Zukko в librechat.yaml

LibreChat — самохостинговый чат с поддержкой многих провайдеров. Сторонние OpenAI-совместимые API в нём подключаются как custom endpoint в файле librechat.yaml. Ниже — рабочий конфиг для Zukko, настройка ключа и Docker, расчёт стоимости и разбор ошибок, из-за которых эндпоинт чаще всего не появляется в интерфейсе.

Как устроена настройка

По документации LibreChat кастомный эндпоинт затрагивает три файла:

• librechat.yaml — описание эндпоинта: имя, адрес API, модели, отображение;
• .env — секреты, на которые librechat.yaml ссылается через ${ИМЯ_ПЕРЕМЕННОЙ};
• docker-compose.override.yml — монтирует librechat.yaml в контейнер (только для Docker).

Файлы librechat.yaml и .env лежат в корне проекта LibreChat. Другой путь к конфигу можно задать переменной CONFIG_PATH.

LibreChat custom endpoint для Zukko: librechat.yaml

version: 1.3.17 # сверьте с актуальной версией конфига в документации LibreChat
cache: true
endpoints:
  custom:
    - name: "Zukko"
      apiKey: "${ZUKKO_API_KEY}"
      baseURL: "https://api.zukko.pro/v1"
      models:
        default: ["claude-sonnet-5", "claude-opus-5-5", "gpt-5.6-sol", "gpt-5.6-luna", "glm-5.3-flash"]
        fetch: true
      titleConvo: true
      titleModel: "glm-5.3-flash"
      modelDisplayLabel: "Zukko"

Разберём поля:

• custom — это список, поэтому каждый эндпоинт начинается с дефиса. Частая ошибка — описать его как обычный словарь без - name:.
• name — название, которое будет видно в переключателе эндпоинтов.
• apiKey — ссылка на переменную окружения. Документация LibreChat рекомендует именно так, а не вписывать ключ в файл.
• baseURL — адрес Zukko, обязательно с /v1.
• models.default — массив моделей, который показывается всегда. Поле обязательное, даже если включён fetch.
• models.fetch: true — LibreChat запросит список моделей у API. Zukko отдаёт его по GET /v1/models, так что новые модели появятся без правки конфига.
• titleConvo и titleModel — LibreChat сам придумывает названия диалогов. Для этой служебной задачи логично взять самую дешёвую модель.
• modelDisplayLabel — подпись модели в чате.

Ключ в .env

ZUKKO_API_KEY=fetch_ваш_ключ

Не кладите ключ Zukko в OPENAI_API_KEY: эта переменная относится к встроенному эндпоинту OpenAI, и LibreChat отправит с ней запросы на серверы OpenAI. Документация LibreChat предупреждает о похожем конфликте имён для OpenRouter, поэтому для кастомных эндпоинтов используйте собственные имена переменных.

Подключение в Docker

Чтобы контейнер увидел librechat.yaml, скопируйте пример override-файла:

cp docker-compose.override.yml.example docker-compose.override.yml

и раскомментируйте монтирование конфига:

services:
  api:
    volumes:
      - type: bind
        source: ./librechat.yaml
        target: /app/librechat.yaml

Override-файл Docker Compose объединяет с основным docker-compose.yml автоматически, поэтому ваши правки переживут обновления LibreChat.

После любых изменений в librechat.yaml или .env LibreChat нужно перезапустить:

docker compose down && docker compose up -d

При локальном запуске без Docker остановите процесс (Ctrl+C) и снова выполните npm run backend.

Проверка

1. Откройте LibreChat и найдите Zukko в списке эндпоинтов.
2. Выберите модель, например claude-sonnet-5, и отправьте короткое сообщение.
3. Если эндпоинта нет, смотрите логи: docker compose logs api. Конфиг можно проверить YAML-валидатором из документации LibreChat.

Два ключа: разделить расходы

Если LibreChat используют и для работы, и для экспериментов, удобно завести в кабинете Zukko два ключа с разными лимитами и описать два эндпоинта:

endpoints:
  custom:
    - name: "Zukko Work"
      apiKey: "${ZUKKO_WORK_KEY}"
      baseURL: "https://api.zukko.pro/v1"
      models:
        default: ["claude-sonnet-5", "claude-opus-5-5"]
        fetch: false
    - name: "Zukko Lab"
      apiKey: "${ZUKKO_LAB_KEY}"
      baseURL: "https://api.zukko.pro/v1"
      models:
        default: ["glm-5.3-flash", "gpt-5.6-luna"]
        fetch: false

С fetch: false пользователи увидят только перечисленные модели. Для надёжности ограничьте и сам ключ: в кабинете у каждого ключа есть список разрешённых моделей, дневной и месячный лимит (подробнее — в документации по лимитам ключей↗).

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

Сколько стоит заголовок диалога: допустим, запрос на название занимает 500 токенов вместе с ответом. На claude-sonnet-5 это 500 × $0.3 / 1 000 000 = $0.00015, на glm-5.3-flash — 500 × $0.04 / 1 000 000 = $0.00002. Сумма маленькая, но набегает на каждый новый диалог, поэтому titleModel стоит указать явно.

Для основных диалогов модель лучше выбирать на своих задачах: возьмите 10–20 типичных запросов, прогоните на двух-трёх моделях и сравните ответы и расход в разделе «Использование» кабинета. Актуальный список моделей — GET https://api.zukko.pro/v1/models или страница «Модели» в кабинете.

Частые проблемы

Zukko не появляется в списке эндпоинтов

Проверьте по порядку: файл лежит в корне проекта (или задан CONFIG_PATH); в Docker он смонтирован через override-файл; YAML без ошибок отступов; у эндпоинта есть все обязательные поля — name, apiKey, baseURL, models.default. Неполный блок LibreChat может молча пропустить, поэтому смотрите docker compose logs api.

401: неверный ключ

Имя переменной в .env не совпадает с тем, что указано в apiKey, или LibreChat не перезапускали после правки .env. Ключ должен начинаться с fetch_ и быть скопирован целиком.

404

В baseURL нет /v1 или, наоборот, добавлен /chat/completions. Нужен ровно https://api.zukko.pro/v1.

400 на моделях Claude

Модели claude-sonnet-5 и claude-opus-5-5 могут отклонять запрос с ошибкой 400, если temperature отличается от 1 или top_p меньше 0.99. По умолчанию LibreChat эти параметры для кастомных эндпоинтов не отправляет, но пользователь может задать их в настройках диалога. Для эндпоинта только с моделями Claude можно добавить dropParams: ["temperature", "top_p"] — тогда LibreChat будет их вырезать из запросов.

402 и 403

402 — закончился баланс, пополните его в кабинете. 403 model_not_allowed_for_key — модели нет в списке разрешённых для этого ключа.

Частые вопросы

Можно ли, чтобы каждый пользователь вводил свой ключ?

Да. Документация LibreChat допускает значение apiKey: "user_provided" — тогда пользователь сам вводит ключ в интерфейсе. Так каждый платит со своего баланса Zukko.

Можно ли подключить Zukko в формате Anthropic?

LibreChat поддерживает для кастомных эндпоинтов параметр provider: "anthropic", а Zukko принимает и Anthropic-формат. Но у нативного Anthropic-клиента адрес указывается без /v1, а список моделей нужно перечислять вручную. Проще оставить OpenAI-совместимый вариант: шлюз сам конвертирует запросы к Claude.

Где смотреть расходы?

В кабинете Zukko, раздел «Использование». Если завели отдельные ключи под разные эндпоинты, расходы будут разделены по ключам.

С чего начать?

Создайте ключ в кабинете Zukko↗, впишите его в .env и скопируйте конфиг выше. Про форматы API подробнее — в документации по Chat Completions↗.