# Настройка Qoder с QCode (BYOK)

> **Последняя проверка**: 2026-11-10 · 📄 По официальной документации (Qoder 0.5.7 и Qoder CLI 1.1.86, обе версии вышли 2026-11-09; документация прочитана 2026-11-10)

## Кратко

| Параметр | Подробности |
|---|---|
| Что это | Qoder — семейство продуктов с ИИ-агентом для программирования: десктопное приложение Qoder, Qoder CLI (`qoder`), Qoder IDE и плагин для JetBrains. Эта страница — про десктопное приложение и CLI. Глобальный сайт — qoder.com (документация на docs.qoder.com), китайский — Qoder CN (документация на docs.qoder.cn) |
| Свой API-ключ? | Да. Официальная страница пользовательских моделей говорит, что Qoder подключает модели сторонних провайдеров по API-ключу, в том числе через пользовательский эндпоинт. Тариф: на странице CLI — «Available edition: Individual plan», в примечании к выпуску десктопа — «Personal plan BYOK» |
| Где настраивать | Десктоп: **Settings** → **Models** → **Add model** → **Provider** → **Custom**. CLI: `/model` → вкладка **Custom** → **Add custom model...** |
| Протоколы | **OpenAI Compatible** (затем **Chat Completions API** или **Responses API**) · **Anthropic Compatible** |
| Значения QCode | Anthropic Compatible: `https://api.qcode.cc/api` · OpenAI Compatible: `https://api.qcode.cc/openai/v1` |
| Доступные модели | Claude ✅ (Anthropic Compatible) · GPT ✅ (OpenAI Compatible) · GLM / Kimi / DeepSeek / Qwen ✅ (оба варианта) · Gemini ❌ (QCode пока не предоставляет модели Gemini) |
| Официальная документация | [Custom models (глобальная)](https://docs.qoder.com/qoder/custom-models) · [Custom models (CN)](https://docs.qoder.cn/qoder/custom-models) · [CLI custom models](https://docs.qoder.com/cli/custom-models) · [Release notes](https://changelog.qoder.com/app) |

Qoder IDE — отдельный продукт того же семейства; на его странице пользовательских моделей (docs.qoder.com/user-guide/chat/custom-models) перечислены только предустановленные провайдеры. Пользовательский Base URL доступен в десктопном приложении Qoder (начиная с 0.1.8, 2026-09-05) и в Qoder CLI, где пользователи личного тарифа настраивают его на странице Custom в `/model` (начиная с 1.1.50, 2026-09-11), — о них и идёт речь ниже.

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

В форме пользовательского эндпоинта два типа провайдера, а у **OpenAI Compatible** нужно ещё выбрать тип API. Выберите строку по семейству моделей:

| Выбор в Qoder | Base URL | ID моделей (примеры) |
|---|---|---|
| **Anthropic Compatible** | `https://api.qcode.cc/api` | `claude-sonnet-5-5`, `claude-opus-5-5`, `deepseek-v4.1-flash`, `glm-5.3` |
| **OpenAI Compatible** + **Chat Completions API** | `https://api.qcode.cc/openai/v1` | `gpt-6.1-sol`, `deepseek-v4.1-flash`, `glm-5.3`, `kimi-k3`, `qwen3.8-max` |
| **OpenAI Compatible** + **Responses API** | `https://api.qcode.cc/openai/v1` | `gpt-6.1-sol`, `gpt-6.1-terra` |

Модели Claude работают только по протоколу Anthropic, поэтому ID вида `claude-…` добавляйте в **Anthropic Compatible**; модели GPT работают только по двум протоколам OpenAI. Четыре китайских семейства работают по обоим. Полная таблица — в разделе [Точки доступа и форматы API](/docs/getting-started/endpoints-and-api-paths); ID моделей копируйте с [qcode.cc/models](https://qcode.cc/models) символ в символ.

**Форма Base URL.** Формулировка Qoder: «enter the exact Base URL supplied by the model service. Qoder displays https://api.example.com/v1 as an example format.» Пример заканчивается на `/v1`, поэтому для обоих вариантов OpenAI указывайте адрес QCode, оканчивающийся на `/v1`. Для Responses API это тоже работает: QCode одинаково обслуживает `/openai/responses` и `/openai/v1/responses`. Какой путь Qoder дописывает для **Anthropic Compatible**, в документации не сказано. Начните с адреса Anthropic от QCode `https://api.qcode.cc/api` (без слэша в конце). Если **Validate and add model** не проходит, укажите `https://api.qcode.cc/api/v1` и проверьте ещё раз: оба адреса ведут к одному эндпоинту QCode `/api/v1/messages`, разница лишь в том, сколько сегментов пути Qoder дописывает сам.

В Азии или Северной Америке можно заменить домен на `asia.qcode.cc` или `us.qcode.cc`; пути остаются теми же.

## Установка

Скачайте десктопное приложение со [страницы загрузки Qoder](https://qoder.com/download) (macOS 12+, Windows 10+ или Linux) и войдите в аккаунт. Для CLI на той же странице приведены команды:

```sh
# macOS / Linux
curl -fsSL https://qoder.com/install | bash

# Windows PowerShell
irm https://qoder.com/install.ps1 | iex
```

У Qoder CN своё приложение и своя документация на docs.qoder.cn. Сверьте свою версию с указанными выше.

## Настройка

### Десктоп: Settings → Models

Шаги взяты с официальной страницы пользовательских моделей, названия элементов — как в английской документации:

1. Откройте **Settings** и выберите **Models** в левой панели навигации.
2. Нажмите **Add model**. Для пользовательского эндпоинта откройте **Provider** и в разделе **Custom** выберите **OpenAI Compatible** или **Anthropic Compatible**.
3. Для **OpenAI Compatible** выберите **Chat Completions API** или **Responses API**.
4. Введите **Base URL**, API-ключ и хотя бы один **Model ID**. Чтобы добавить ещё модели для того же эндпоинта, нажмите **Add Model ID**.
5. Задайте возможности модели, которые показывает страница: **Display name**, **Context window** (выберите поддерживаемые значения, затем **Default context window**), **Vision** (включите, если модель принимает изображения) и **Thinking** (включите, если модель поддерживает рассуждения, и выберите уровни усилия).
6. Нажмите **Validate and add model**. «Qoder validates the connection and saves the model after validation succeeds.»
7. Выберите новую модель в окне чата.

Что вводить для QCode (заглушка ключа — `cr_xxx`):

| Поле | Anthropic Compatible | OpenAI Compatible |
|---|---|---|
| Base URL | `https://api.qcode.cc/api` | `https://api.qcode.cc/openai/v1` |
| Тип API | — | **Chat Completions API** (для GPT также **Responses API**) |
| API-ключ | `cr_xxx` | `cr_xxx` |
| Model ID | `claude-sonnet-5-5` | `gpt-6.1-sol` |

Добавьте по одной записи на каждый нужный протокол; у каждой записи свой Base URL.

**Чем отличаются глобальная версия и CN.** На глобальной странице среди предустановленных провайдеров перечислены Alibaba Cloud Model Studio, DeepSeek, Z.ai, Kimi, MiniMax, Xiaomi MIMO, OpenAI, Google и OpenRouter. На странице CN — Alibaba Cloud Model Studio, DeepSeek, Zhipu, Kimi, MiniMax и Xiaomi MIMO, без OpenAI, Google и OpenRouter. Пользовательских провайдеров в обеих версиях два — **OpenAI Compatible** и **Anthropic Compatible**, — и шаги одинаковые.

Чтобы позже сменить ключ, используйте действие **Edit** на панели **Models**; **Delete** удаляет модель.

### CLI: /model → Custom

1. Запустите Qoder CLI и введите `/model`.
2. Перейдите на вкладку **Custom**.
3. Выберите **Add custom model...** и нажмите Enter.
4. Пройдите мастер: «Provider → model type → model», затем введите API-ключ и другие запрошенные данные.
5. После успешной проверки конфигурация сохраняется автоматически, и модель сразу доступна для выбора. Выберите её на вкладке **Custom**; клавиша `d` на выбранной модели удаляет её.

На официальной странице также сказано: «Do not configure BYOK manually in settings.json; the available providers, models, and credential fields are determined by the BYOK catalog available to the current account.» Поля мастера на странице CLI не перечислены. В примечании к выпуску CLI 1.1.50 сказано, что пользователи личного тарифа могут настраивать модели BYOK «with custom URL endpoints from the Custom page in /model», а официальный аккаунт Qoder в X описал это как ввод Base URL, Model ID и API-ключа. В эти поля вводите значения QCode из таблицы выше.

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

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

```bash
KEY="cr_your_key"

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

# Anthropic Compatible
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-5","max_tokens":32,
       "messages":[{"role":"user","content":"ping"}]}'
```

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

На случай, если модель не добавляется, официальный FAQ перечисляет пять проверок. Как они соотносятся с QCode:

| Официальная проверка | В QCode |
|---|---|
| "Whether the Base URL is complete and the selected compatible protocol and API type match the endpoint" | Anthropic Compatible → `https://api.qcode.cc/api` (или `https://api.qcode.cc/api/v1`, см. выше); OpenAI Compatible → `https://api.qcode.cc/openai/v1`, без `/` в конце |
| "Whether the API key is correct with no extra spaces, and has not expired or been disabled" | Вставьте ключ `cr_` заново, без пробелов |
| "Whether the Model ID is correct and accessible to the provider account" | Скопируйте ID со страницы [qcode.cc/models](https://qcode.cc/models) |
| "Whether the provider account has sufficient balance" | Проверьте баланс в панели QCode |
| "Whether the network connection is normal" | Попробуйте `asia.qcode.cc` или `us.qcode.cc` с теми же путями |

Два сообщения со стороны QCode: `model_not_available_on_endpoint` означает, что ID `claude-…` добавлен в вариант OpenAI, — добавьте его в **Anthropic Compatible**; это ошибка выбора протокола, а не ключа. `Invalid API key` — проблема ключа.

Для CLI официальная страница говорит: если нет вкладки **Custom** или пункта добавления, убедитесь, что BYOK доступен для текущего аккаунта и тарифа; если нет нужного провайдера или модели, ориентируйтесь на актуальный каталог, который показывает мастер.

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

- Официально: «Image and video generation are currently unavailable when using models connected with your own API key (BYOK).»
- Официально: плата за пользовательские модели списывается с API-аккаунта провайдера и «do not use Qoder Credits». Repo Wiki работает на фиксированной модели и по-прежнему расходует Qoder Credits.
- Пример `https://api.example.com/v1` в Qoder — только образец формата; какой путь Qoder дописывает для каждого протокола, документация не описывает, поэтому окончательный ответ даёт результат **Validate and add model**.
- QoderWork — отдельный продукт. На его странице моделей перечислены уровни Premium, Advanced и Standard, а также Qwen3.7-Max и Qwen3.7-Plus; пункта для пользовательской модели там нет (на 2026-11-10). На странице загрузки Qoder сказано, что QoderWork прекратит работу 5 сентября 2027 года, и рекомендуется перейти на Qoder Desktop со встроенными инструментами импорта данных.
- Согласно официальному уведомлению, уровень моделей Lite убран из селектора моделей 18 сентября 2026 года в 14:00 по сингапурскому времени (UTC+8).

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

- [Точки доступа и форматы API](/docs/getting-started/endpoints-and-api-paths) — таблица «протокол × семейство моделей»
- [Обзор совместимости инструментов](/docs/ide/tool-compatibility) — какой инструмент какой протокол поддерживает
- [DeepSeek Harness](/docs/ide/deepseek-harness) — ещё один инструмент с формой пользовательской модели
- [LobsterAI](/docs/ide/lobsterai) — десктопный агент, пользовательские провайдеры которого тоже принимают форматы Anthropic и OpenAI
- [Китайские модели](/docs/usage/cn-models) — ID и пути GLM / Kimi / DeepSeek / Qwen
- [Руководство по Qoder custom model BYOK на qcode.cc](https://qcode.cc/ru/qoder-custom-model-byok-setup) — даты и контекст