# Подключение DeepSeek Harness (dsh) к QCode

> **Последняя проверка**: 2026-11-09 · 📄 По официальной документации (DeepSeek Harness 0.2.2-rc.1, опубликован на npm и GitHub 2026-11-04; документация репозитория прочитана 2026-11-09)

## Кратко

| Параметр | Подробности |
|---|---|
| Что это | DeepSeek Harness (`dsh`) — открытый агентский харнесс от DeepSeek AI; веб-интерфейс запускается командой `dsh web` |
| Доступные модели | Claude ✅ (провайдер Anthropic Messages) · GPT ✅ · GLM / Kimi / DeepSeek / Qwen ✅ (провайдер OpenAI Chat Completions) · Gemini ❌ (QCode пока не предоставляет модели Gemini) |
| Протокол и Base URL | OpenAI Chat Completions: `https://api.qcode.cc/openai/v1` · Anthropic Messages: `https://api.qcode.cc/api` |
| Где настраивается | **Settings → Models** → **Add model provider** → **Custom model API** |
| Куда записывается | `$DSH_HOME/profiles/<profile>/cordis.patch.yml`; ключ — в `$DSH_HOME/.credentials.yaml` |
| Официальная документация | [Настройка моделей](https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/user/guide/providers.md) · [репозиторий](https://github.com/deepseek-ai/deepseek-harness) |

DeepSeek Harness находится в режиме предварительной версии для разработчиков. Официальный README гласит: "THERE WILL BE COMPATIBILITY-BREAKING CHANGES." Сверьте используемую версию с этой страницей.

## Какой протокол выбрать

**API protocol** пользовательского провайдера должен совпадать с протоколом шлюза. Переключатель предлагает три варианта: OpenAI Chat Completions, OpenAI Responses и Anthropic Messages; они сохраняются как `openai-completions`, `openai-responses` и `anthropic-messages`. Один провайдер говорит на одном протоколе, поэтому шлюзу с двумя протоколами нужны два провайдера.

QCode обслуживает Claude только по протоколу Anthropic, а GPT — только по протоколам OpenAI; четыре китайских семейства работают в обоих. См. [Эндпоинты и пути API](/docs/getting-started/endpoints-and-api-paths). Получается два провайдера:

| Провайдер | API protocol | Base URL | ID моделей (примеры) |
|---|---|---|---|
| `qcode` | OpenAI Chat Completions (`openai-completions`) | `https://api.qcode.cc/openai/v1` | `gpt-6-sol`, `deepseek-v4-pro`, `glm-5.3`, `kimi-k3`, `qwen3.8-max` |
| `qcode-claude` | Anthropic Messages (`anthropic-messages`) | `https://api.qcode.cc/api` | `claude-sonnet-5`, `claude-opus-5` |

ID провайдеров — это имена, которые вы выбираете сами. Используйте ID моделей с [qcode.cc/models](https://qcode.cc/models) буквально, символ в символ; китайские ID также перечислены в разделе [Китайские модели](/docs/usage/cn-models). Не добавляйте `/` в конец Base URL и не помещайте ID `claude-…` за OpenAI Base URL.

## Установка

DeepSeek Harness требует Node.js 24.9 или новее (npm-пакет объявляет `node >=24.9.0`, а в примечаниях к выпуску v0.2.2-rc.1 сказано: "Raise the minimum supported Node.js version to 24.9."). Установите Node.js и выполните:

```sh
npx @deepseek-ai/dsh web
```

Команда по умолчанию поднимает веб-интерфейс на `http://127.0.0.1:3080` и при локальном запуске открывает его в браузере по умолчанию. При запуске по SSH выводится только URL хоста. Флаг `--no-open` запускает сервер без открытия браузера.

Чтобы запустить из клона репозитория:

```sh
git clone https://github.com/deepseek-ai/deepseek-harness.git
cd deepseek-harness
pnpm install
pnpm run build
pnpm dsh web
```

`$DSH_HOME` — корень данных харнесса; по умолчанию это `~/.dsh`, если не задана переменная окружения `DSH_HOME`. Перед запуском ознакомьтесь с официальным [уведомлением о безопасности](https://github.com/deepseek-ai/deepseek-harness/blob/master/SAFETY.md).

## Настройка

Изменения моделей вступают в силу со следующего запроса без перезапуска сервера.

Веб-интерфейс показывается на языке браузера. Шаги ниже написаны по английскому интерфейсу; в русском интерфейсе пункты называются так:

| Английский интерфейс | Русский интерфейс |
|---|---|
| Settings → Models | Настройки → Модели |
| Add model provider · Custom model API | Добавить поставщика моделей · Пользовательская модель API |
| Provider ID · Display name · Base URL | Идентификатор поставщика · Отображаемое имя · Базовый URL |
| API protocol · API key | Протокол API · Ключ API |
| Models · Add model · Fetch available models | Модели · Добавить модель · Получить доступные модели |
| Create provider | Создать поставщика |
| Model options · Reasoning levels · Image | Варианты модели · Уровни рассуждения · Изображение |

1. Откройте веб-интерфейс, затем **Settings → Models**, и выберите **Add model provider**.
2. Переключите карточку на **Custom model API**. Она предназначена для ретранслятора (relay), корпоративного шлюза, собственного сервера или любого провайдера, которого нет в установленном каталоге.
3. Заполните форму для первого провайдера:
   - **Provider ID**: `qcode` (строчными буквами; ID нельзя изменить, выбирайте осознанно)
   - **Display name**: `QCode` (необязательно)
   - **Base URL**: `https://api.qcode.cc/openai/v1`
   - **API protocol**: OpenAI Chat Completions
   - **API key**: ваш ключ QCode (начинается с `cr_`)
4. В списке **Models** формы (в официальном руководстве он называется каталогом моделей) нажмите **Add model** и введите ID моделей, например `deepseek-v4-pro` и `gpt-6-sol`. **Fetch available models** запрашивает у эндпоинта список моделей; это всего лишь удобная функция, и официальное руководство говорит, что при сбое или пустом списке добавленные вручную ID работают так же. На QCode эндпоинт OpenAI перечисляет модели GPT, поэтому китайские ID добавляйте вручную.
5. Нажмите **Create provider**. Затем повторите с Provider ID `qcode-claude`, Display name `QCode Claude`, Base URL `https://api.qcode.cc/api`, **API protocol** = Anthropic Messages, тем же ключом и моделью `claude-sonnet-5` и снова нажмите **Create provider**.
6. Откройте перечень моделей и выберите модель. Выбранная модель также становится моделью по умолчанию для новых сессий.

Ключи доступны только для записи: после сохранения страница получает лишь скрытое описание, но никогда сам секрет. Ключ хранится в `$DSH_HOME/.credentials.yaml`, а в настройках остаётся только ссылка на него.

### Что записывает страница

Для справки: те же провайдеры в `$DSH_HOME/profiles/<profile>/cordis.patch.yml` выглядят так. При стандартном запуске `dsh web` `<profile>` равен `web`, поэтому путь — `$DSH_HOME/profiles/web/cordis.patch.yml`. Этот документ страница записывает за вас; редактируйте его вручную, только если нужна настройка, которой нет в форме.

```yaml
- id: llm-pi-ai
  config:
    providers:
      qcode:
        displayName: QCode
        apiKeyEnv: QCODE_API_KEY
        api: openai-completions
        baseURL: https://api.qcode.cc/openai/v1
        models:
          - id: deepseek-v4-pro
          - id: gpt-6-sol
      qcode-claude:
        displayName: QCode Claude
        apiKeyEnv: QCODE_CLAUDE_API_KEY
        api: anthropic-messages
        baseURL: https://api.qcode.cc/api
        models:
          - id: claude-sonnet-5
```

`apiKeyEnv` — это ссылка на учётные данные: страница выводит её из Provider ID (`qcode` → `QCODE_API_KEY`, `qcode-claude` → `QCODE_CLAUDE_API_KEY`) и сохраняет введённый ключ под этим именем. В официальной записи по ошибке `MISSING_CREDENTIAL` сказано: сохраните ключ провайдера через страницу Models либо задайте указанную переменную окружения. Переопределение конфигурации Cordis заменяет всю конфигурацию записи, поэтому при правке существующего переопределения сохраняйте остальные провайдеры.

## Проверка связи

1. Выберите добавленную модель в перечне моделей и отправьте короткое сообщение вроде `ping`.
2. Откройте [probe.qcode.cc](https://probe.qcode.cc), введите ключ QCode и проверьте, что запрос появился с этой моделью.
3. Чтобы проверить ключ и путь без dsh:

```bash
KEY="cr_your_key"

# OpenAI Chat Completions provider
curl -sS https://api.qcode.cc/openai/v1/chat/completions \
  -H "Authorization: Bearer $KEY" \
  -H "content-type: application/json" \
  -d '{"model":"deepseek-v4-pro","max_tokens":32,"messages":[{"role":"user","content":"ping"}]}'

# Anthropic Messages provider
curl -sS https://api.qcode.cc/api/v1/messages \
  -H "x-api-key: $KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model":"claude-sonnet-5","max_tokens":32,"messages":[{"role":"user","content":"ping"}]}'
```

## Диагностика

| Симптом | Причина | Решение |
|---|---|---|
| `MISSING_CREDENTIAL` | Ключ не сохранён или указанная переменная окружения пуста | Сохраните ключ через **Settings → Models** либо задайте переменную из `apiKeyEnv` перед запуском `dsh` |
| `UNKNOWN_MODEL` | Выбранной модели нет в списке провайдера | Выберите настроенную модель или добавьте её ID в провайдер |
| Fetch available models возвращает 401 | Неверный ключ | Проверьте ключ; обнаружение моделей обращается к совместимому с OpenAI эндпоинту `GET /models` |
| Список пуст или запрос падает | Формат списка эндпоинта не читается функцией обнаружения | Введите ID моделей вручную |
| `model_not_available_on_endpoint` | ID `claude-…` добавлен в провайдер OpenAI Chat Completions | Поместите ID Claude в провайдер Anthropic Messages с Base URL `https://api.qcode.cc/api` |
| 404 | Слэш в конце Base URL или неверный префикс пути | Сверьтесь с [Эндпоинты и пути API](/docs/getting-started/endpoints-and-api-paths) |
| Шлюз отклоняет все запросы при верных ключе и URL | Форма запроса отличается от OpenAI | Официальный совет: задайте на маршруте `compat.supportsDeveloperRole: false` и `compat.maxTokensField: max_tokens` |
| Падают только модели с рассуждениями | pi-ai отправляет их системный запрос с ролью `developer` | Установите `compat.supportsDeveloperRole: false` |
| Для модели, добавленной вручную, нет меню Effort | Модель не объявляет уровни рассуждений | Включите **Reasoning levels** в **Model options** модели |

## Известные ограничения

- Предварительная версия для разработчиков: поля и поведение могут меняться между выпусками; страница сверена с 0.2.2-rc.1, которую npm помечает как `latest` на 2026-11-09.
- В форме нет поля для переключателей `compat`; задайте их на маршруте в `cordis.patch.yml`, как описано в официальном руководстве.
- Модель, добавленная вручную, не объявляет уровни рассуждений, пока вы их не добавите, и остаётся текстовой, пока в её **Model options** не выбран **Image** (см. разделы официального руководства о вводе изображений и уровне рассуждений).

## Смежные документы

- [Эндпоинты и пути API](/docs/getting-started/endpoints-and-api-paths) — таблица «протокол × семейство моделей»
- [Китайские модели](/docs/usage/cn-models) — ID и пути GLM / Kimi / DeepSeek / Qwen
- [CodeWhale (DeepSeek-TUI)](/docs/ide/deepseek-tui) — ещё один терминальный агент с обоими протоколами
- [Обзор совместимости инструментов](/docs/ide/tool-compatibility) — какой протокол у какого инструмента
- [T3 Code](/docs/ide/t3code) — панель управления, которая запускает Claude Code и Codex
- [Руководство по DeepSeek Harness на qcode.cc](https://qcode.cc/ru/deepseek-harness-guide) — контекст и сценарии использования