DeepSeek Harness: как подключить API-ключ kosareva.cloud и настроить собственный провайдер

Через kosareva.cloud DeepSeek Harness подключается к OpenAI-совместимому API: достаточно указать базовый URL, ключ, протокол и нужную модель. После сохранения провайдер появляется в списке моделей, и Harness можно использовать как локальный агент с единым ключом к моделям.

Что это такое

DeepSeek Harness — это открытая среда для запуска AI-агентов, в которой модели, инструменты, сессии и режимы работы подключаются как плагины. Поэтому к Harness можно добавить не только встроенный источник моделей, но и собственный OpenAI-совместимый провайдер — например, endpoint kosareva.cloud.

Это удобно, если вы хотите запускать Harness локально, но обращаться к моделям через единый API-ключ: не менять код самого Harness, не хранить отдельные ключи для каждой модели и выбирать модель прямо в интерфейсе.

Кратко: что понадобится

Для подключения подготовьте:

• установленный DeepSeek Harness;
• аккаунт и баланс на kosareva.cloud;
• API-ключ, созданный в личном кабинете;
• базовый URL https://api.kosareva.cloud/v1;
• идентификатор модели, которую вы хотите использовать.

В Harness используется именно базовый URL с /v1. Добавлять к нему /chat/completions в поле адреса не нужно: Harness сам формирует конечный маршрут запроса.

Установка DeepSeek Harness

Если Harness ещё не установлен, запустите Web UI через Node.js и npm:

npx @deepseek-ai/dsh web

По умолчанию локальный интерфейс открывается по адресу:

http://127.0.0.1:3080

Если вы запускаете Harness на удалённом сервере, подключитесь к Web UI через SSH-туннель или используйте предусмотренный вашей инфраструктурой защищённый доступ. Сам API-ключ при этом не нужно передавать в командной строке или добавлять в публичный репозиторий.

Как получить API-ключ kosareva.cloud

1. Откройте личный кабинет kosareva.cloud.
2. Войдите в аккаунт или зарегистрируйтесь.
3. Пополните баланс удобным способом.
4. Откройте раздел API-ключи.
5. Создайте новый ключ и скопируйте его.

Ключ показывается как секретное значение. Сохраните его в менеджере секретов или в защищённом хранилище. Не вставляйте настоящий ключ в статьи, скриншоты, Git-репозитории и сообщения, которые могут быть доступны другим людям.

В одном ключе kosareva.cloud можно использовать разные доступные модели: в Harness меняется только выбранный model, а адрес API и авторизация остаются прежними.

Подключение через интерфейс Harness

Откройте DeepSeek Harness и перейдите в:

Settings → Models → Add a custom provider

В форме собственного провайдера заполните поля так:

Поле	Что указать
Provider ID	kosareva-cloud
Display name	kosareva.cloud
Base URL	https://api.kosareva.cloud/v1
API protocol	openai-completions
API key	ваш ключ kosareva.cloud
Model	идентификатор нужной модели

Provider ID должен быть в нижнем регистре. Это постоянный идентификатор провайдера: его используют сохранённые сессии, настройки модели и ссылки на учётные данные. Если позже изменить только отображаемое имя, ничего не сломается. Если потребуется изменить сам Provider ID, создайте нового провайдера и удалите старый.

После заполнения нажмите Fetch available models, если endpoint возвращает список моделей. Harness выполнит запрос к GET https://api.kosareva.cloud/v1/models и покажет доступные варианты.

Выберите нужные модели и нажмите Save. Если автоматическое получение списка не сработало, добавьте модель вручную. Это не означает, что ключ неверный: некоторые конфигурации endpoint могут не предоставлять каталог моделей, хотя обычные запросы работают.

Как выбрать модель и начать работу

После сохранения провайдер появится в списке моделей Harness.

1. Откройте селектор модели.
2. Выберите kosareva.cloud.
3. Выберите нужную модель.
4. Создайте новую сессию.
5. Отправьте первый запрос.

Выбранная модель становится моделью по умолчанию для новых сессий. Уже начатая сессия сохраняет модель, с которой она была запущена, поэтому для проверки другого варианта лучше создать новую сессию.

В интерфейсе Harness можно использовать стандартный режим с инструментами, минимальный режим или другие доступные режимы. Провайдер отвечает за запрос к модели, а Harness — за агентный цикл, инструменты, сессии и отображение результата.

Вариант через файл настроек

Если вы запускаете Harness на сервере или хотите хранить конфигурацию рядом с инфраструктурой, собственного провайдера можно описать в $DSH_HOME/settings.yaml.

Пример:

llm-pi-ai:
  providers:
    kosareva-cloud:
      displayName: kosareva.cloud
      apiKeyEnv: KOSAREVA_API_KEY
      api: openai-completions
      baseURL: https://api.kosareva.cloud/v1
      models:
        - id: gpt-4o

Перед запуском Harness задайте ключ через переменную окружения:

export KOSAREVA_API_KEY="ваш_ключ_kosareva.cloud"
npx @deepseek-ai/dsh web

Такой способ предпочтительнее для серверов и командной работы: секрет не попадает в файл настроек и не хранится непосредственно в shell-команде после завершения текущей сессии. В постоянной инфраструктуре переменную лучше передавать через секреты Docker, systemd, CI/CD или другой используемый вами менеджер секретов.

Название переменной в примере можно изменить. Важно, чтобы значение apiKeyEnv в settings.yaml совпадало с именем переменной окружения.

Быстрая проверка API до настройки Harness

Если Harness не подключается, сначала проверьте endpoint отдельным запросом. Это помогает разделить проблемы конфигурации Harness и проблемы ключа или сети.

Проверка списка моделей

curl https://api.kosareva.cloud/v1/models \
  -H "Authorization: Bearer $KOSAREVA_API_KEY"

Тестовый запрос к модели

curl https://api.kosareva.cloud/v1/chat/completions \
  -H "Authorization: Bearer $KOSAREVA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o",
    "messages": [
      {"role": "user", "content": "Ответь одним предложением: подключение работает?"}
    ],
    "stream": false
  }'

Вместо gpt-4o укажите модель, доступную в вашем кабинете kosareva.cloud. Если запрос возвращает ответ модели, endpoint и ключ работают, а дальнейшую диагностику нужно проводить в настройках Harness.

Совместимость запроса и дополнительные настройки

OpenAI-совместимость не означает, что каждый клиент отправляет запросы абсолютно одинаково. Harness определяет формат запроса по выбранному протоколу. Для kosareva.cloud в стандартном сценарии используйте:

api: openai-completions
baseURL: https://api.kosareva.cloud/v1

Если ключ и адрес правильные, но шлюз отклоняет каждый запрос, проверьте совместимость формата. Для некоторых моделей Harness может отправлять системный prompt как роль developer или использовать поле max_completion_tokens, тогда как endpoint ожидает system и max_tokens.

В таком случае добавьте к провайдеру совместимые параметры:

llm-pi-ai:
  providers:
    kosareva-cloud:
      displayName: kosareva.cloud
      apiKeyEnv: KOSAREVA_API_KEY
      api: openai-completions
      baseURL: https://api.kosareva.cloud/v1
      compat:
        supportsDeveloperRole: false
        maxTokensField: max_tokens
      models:
        - id: gpt-4o

Не добавляйте параметры совместимости заранее без причины. Они меняют форму запроса, поэтому сначала проверьте обычную конфигурацию, а затем включайте только те настройки, которые нужны конкретной модели или версии Harness.

Изображения и модели с vision

Модель, добавленная вручную, может считаться текстовой, пока в настройках не указано обратное. Если вы планируете отправлять изображения, объявите такую возможность для конкретной модели:

llm-pi-ai:
  providers:
    kosareva-cloud:
      apiKeyEnv: KOSAREVA_API_KEY
      api: openai-completions
      baseURL: https://api.kosareva.cloud/v1
      models:
        - id: gpt-4o
          input: [text, image]

Эта запись только сообщает Harness, что endpoint должен принимать текст и изображения. Она не добавляет vision-возможности модели автоматически. Указывайте image только для тех моделей, которые действительно поддерживают изображения через ваш API-маршрут.

Частые ошибки

Ошибка MISSING_CREDENTIAL

Harness не нашёл ключ. Сохраните его через страницу Settings → Models или проверьте, что переменная окружения существует и называется точно так же, как значение apiKeyEnv.

Ошибка UNKNOWN_MODEL

Идентификатор модели отсутствует в конфигурации. Выберите модель из найденного каталога или добавьте её вручную в список models.

При получении моделей появляется 401

Сервер отклонил авторизацию. Проверьте активность ключа, отсутствие лишних пробелов и заголовок Authorization: Bearer. Также убедитесь, что в Base URL указан адрес https://api.kosareva.cloud/v1, а не конечный маршрут /chat/completions.

Модель добавилась, но запрос не отправляется

Проверьте три значения: api: openai-completions, базовый URL и точный ID модели. Затем создайте новую сессию и повторите запрос. Если API работает через cURL, но не работает через Harness, попробуйте параметры compat из раздела выше.

В списке нет нужной модели

Нажмите Fetch available models ещё раз. Если endpoint не отдаёт каталог, добавьте модель вручную по её идентификатору. При ручном добавлении особенно важно указать правильный model — Harness не сможет проверить опечатку до отправки запроса.

Безопасность API-ключа

• храните ключ в переменной окружения или менеджере секретов;
• не коммитьте .env и settings.yaml с реальным секретом в Git;
• создавайте отдельные ключи для разных окружений;
• отзывайте ключ при утечке;
• используйте лимиты и мониторинг расходов в личном кабинете;
• не передавайте ключ в URL, логах и текстах запросов.

В интерфейсе Harness сохранённый ключ отображается в скрытом виде. Это нормальное поведение: приложение не должно возвращать секрет в открытом виде после сохранения.

FAQ

Можно ли подключить kosareva.cloud к DeepSeek Harness без изменения исходного кода?

Да. Создайте собственного провайдера в Settings → Models → Add a custom provider, укажите OpenAI-совместимый протокол, базовый URL kosareva.cloud, API-ключ и модель. Исходный код DeepSeek Harness менять не требуется.

Какой Base URL указать в DeepSeek Harness?

Используйте https://api.kosareva.cloud/v1. Конечные пути вроде /chat/completions в это поле добавлять не нужно: их формирует Harness.

Что делать, если Harness не видит модели kosareva.cloud?

Проверьте ключ и нажмите Fetch available models. Если каталог не загрузился, добавьте модель вручную. Для ручной записи нужен точный идентификатор модели из кабинета kosareva.cloud.

Где хранится ключ при настройке через интерфейс?

DeepSeek Harness хранит секрет в своём защищённом хранилище учётных данных, а в настройках использует ссылку на него. Сам ключ после сохранения не показывается в открытом виде.

Поддерживает ли такая схема агентные инструменты Harness?

Да. kosareva.cloud отвечает за API-доступ к выбранной модели, а DeepSeek Harness продолжает управлять сессиями, инструментами, режимами работы и агентным циклом. Возможности конкретного инструмента зависят от выбранной модели и её API-совместимости.

Итог

Подключение kosareva.cloud к DeepSeek Harness сводится к четырём значениям: Provider ID, базовый URL, OpenAI-совместимый протокол и API-ключ. После сохранения выберите модель в селекторе и создайте новую сессию — Harness будет использовать kosareva.cloud как собственный API-маршрут, а все агентные функции останутся доступными в локальном интерфейсе.

Если автоматический каталог моделей не срабатывает, это не блокирует настройку: провайдера можно сохранить с моделью, добавленной вручную. Для серверного запуска используйте переменную окружения KOSAREVA_API_KEY, чтобы не хранить секрет в конфигурации и исходном коде.