# CodeBuddy: кастомные модели через QCode

> **Последняя проверка**: 2026-11-10 · 📄 По официальной документации (CodeBuddy IDE 4.12.4, выпущена 2026-11-06; документация CLI для v2.182.0) · ✅ Подключение к QCode проверено на CodeBuddy Code CLI 2.182.0 (2026-11-10)

Да, в CodeBuddy можно подключить свой ключ: кастомные модели описываются в `models.json` (на уровне пользователя — `~/.codebuddy/models.json`), а официальная документация говорит: «Currently only supports OpenAI interface format API». На 2026-11-10 проверено на CodeBuddy Code CLI 2.182.0: QCode работает через OpenAI Chat Completions (`url` — полный путь) и OpenAI Responses (`url` — базовый адрес), а CLI использует эти модели без входа в аккаунт Tencent. Шаги для IDE описаны по официальной документации.

## Кратко

| Пункт | Подробности |
|---|---|
| Можно ли свой ключ? | Да. IDE и CLI читают `models.json`; CLI работает с ним без входа в аккаунт (✅ проверено) |
| Доступные модели | Claude ❌ (этот протокол — не эндпоинт Anthropic) · GPT ✅ · китайские модели ✅ · Gemini ❌ (QCode пока не предоставляет Gemini) |
| Chat Completions | `url`: `https://api.qcode.cc/openai/v1/chat/completions` (полный путь) · ✅ проверено в CLI |
| Responses (CLI) | `"api": "openai-responses"`, `url`: `https://api.qcode.cc/openai/v1` · ✅ проверено в CLI |
| Переменные окружения (CLI) | `CODEBUDDY_BASE_URL=https://api.qcode.cc/openai/v1` (OpenAI Chat) · ✅ проверено в CLI |
| Файлы конфигурации | уровень пользователя `~/.codebuddy/models.json`; уровень проекта `<project-root>/.codebuddy/models.json` |
| Официальная документация | [models.json для IDE](https://www.codebuddy.ai/docs/ide/Features/models) · [models.json для CLI](https://www.codebuddy.ai/docs/cli/models) · [переменные окружения CLI](https://www.codebuddy.ai/docs/cli/env-vars) |

CodeBuddy — инструмент для программирования с ИИ от Tencent Cloud. Он существует в трёх формах: плагин для VS Code и IDE JetBrains, отдельная CodeBuddy IDE и CodeBuddy Code — инструмент командной строки с командой `codebuddy`. Сайты — [codebuddy.cn](https://www.codebuddy.cn) (материковый Китай) и [codebuddy.ai](https://www.codebuddy.ai) (международный); путь к файлу кастомных моделей в обеих документациях одинаков. WorkBuddy, офисный агент той же команды, построен на той же основе; см. [свою модель в WorkBuddy](/docs/ide/workbuddy).

QCode.cc не связан с Tencent или CodeBuddy. Интерфейс и поля зависят от установленной у вас сборки.

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

| Вход | Протокол | Значение для QCode | Модели |
|---|---|---|---|
| `models.json` (IDE и CLI) | OpenAI Chat Completions | `url`: `https://api.qcode.cc/openai/v1/chat/completions` | GPT, DeepSeek / GLM / Kimi / Qwen |
| `models.json` с `"api": "openai-responses"` (CLI) | OpenAI Responses | `url`: `https://api.qcode.cc/openai/v1` | GPT |
| `CODEBUDDY_BASE_URL` (CLI) | OpenAI Chat Completions | `https://api.qcode.cc/openai/v1` | GPT, DeepSeek / GLM / Kimi / Qwen |

Через эти протоколы в QCode доступны GPT и китайские модели. Модели Claude работают через эндпоинт Anthropic, а кастомные модели CodeBuddy этот протокол не используют. Если нужен Claude, возьмите инструмент с поддержкой эндпоинта Anthropic — например, [Claude Code](/docs/getting-started/installation), [ZCode](/docs/ide/zcode) или [Qoder](/docs/ide/qoder). Три протокола сравниваются в разделе [Точки доступа и форматы API](/docs/getting-started/endpoints-and-api-paths). Из материкового Китая можно использовать `asia.qcode.cc` вместо `api.qcode.cc`: путь тот же, ключ тот же.

## Установка CodeBuddy Code CLI

Официальное руководство по установке приводит такой способ (требуется Node.js 18.20 или новее); именно он использовался в проверке 2026-11-10:

```bash
npm install -g @tencent-ai/codebuddy-code
```

Без Node.js руководство предлагает Homebrew и нативный бинарный файл (Beta):

```bash
curl -fsSL https://www.codebuddy.cn/cli/install.sh | bash
```

В Windows PowerShell используйте `irm https://www.codebuddy.cn/cli/install.ps1 | iex`. Установку проверьте командой `codebuddy --version` (в проверке была версия 2.182.0). Кастомные модели ниже работают без входа в аккаунт Tencent. IDE и плагин скачиваются с [codebuddy.ai](https://www.codebuddy.ai); если вам нужна только IDE, этот раздел можно пропустить.

## Настройка models.json

### Где лежат файлы

Документация описывает два уровня:

- Уровень пользователя: `~/.codebuddy/models.json`, глобальный, действует для всех проектов
- Уровень проекта: `<project-root>/.codebuddy/models.json`, приоритет выше пользовательского

Порядок слияния: уровень проекта, затем уровень пользователя, затем встроенные значения по умолчанию. Модель с тем же `id` переопределяется, модель с другим `id` добавляется. IDE и CLI читают одни и те же пути.

### CLI: минимальный models.json (✅ проверено)

Сохраните это как `~/.codebuddy/models.json`. Первая запись работает через Chat Completions, вторая — через Responses; ключ берётся из переменной окружения:

```json
{
  "models": [
    {
      "id": "deepseek-v4-flash",
      "name": "QCode DeepSeek V4 Flash",
      "vendor": "QCode",
      "url": "https://api.qcode.cc/openai/v1/chat/completions",
      "apiKey": "${QCODE_API_KEY}",
      "maxInputTokens": 128000,
      "maxOutputTokens": 8192,
      "supportsToolCall": true
    },
    {
      "id": "gpt-6.1-terra",
      "name": "QCode GPT-6.1 Terra",
      "vendor": "QCode",
      "api": "openai-responses",
      "url": "https://api.qcode.cc/openai/v1",
      "apiKey": "${QCODE_API_KEY}",
      "maxInputTokens": 128000,
      "maxOutputTokens": 8192,
      "supportsToolCall": true
    }
  ],
  "availableModels": ["deepseek-v4-flash", "gpt-6.1-terra"]
}
```

Затем экспортируйте ключ и отправьте каждой модели короткий тест:

```bash
export QCODE_API_KEY="cr_xxx"
codebuddy -p "Reply with exactly: OK" --model deepseek-v4-flash
codebuddy -p "Reply with exactly: OK" --model gpt-6.1-terra
```

Ответ `OK` означает, что модель работает. `id` отправляется в QCode как имя модели, поэтому это должен быть действующий id со страницы [qcode.cc/models](https://qcode.cc/models), символ в символ. Для записей Chat подойдут также `gpt-6.1-sol`, `deepseek-v4-pro`, `glm-5.3`, `kimi-k3` и `qwen3.8-max` (см. [Китайские модели](/docs/usage/cn-models)); для записей Responses — id моделей GPT. Цены по моделям — на https://qcode.cc/models. `maxInputTokens`, `maxOutputTokens` и флаги изображений и рассуждений выставьте по возможностям выбранной модели.

### Два правила для `url`

Для Chat Completions (по умолчанию) официальная формулировка такая: «url field must be the complete interface path, typically ending with /chat/completions», и приводятся неверные примеры:

```text
❌ https://api.openai.com/v1
❌ https://api.myservice.com
❌ http://localhost:11434
```

Если `api` равно `openai-responses`, правило обратное. Официальная формулировка: «With api set to openai-responses, the model uses the OpenAI Responses API: requests go to {url}/responses» и «url takes the base URL; a trailing /responses is optional.»

| Значение `url` | Результат |
|---|---|
| `https://api.qcode.cc/openai/v1/chat/completions` | ✅ Chat Completions (проверено) |
| `https://api.qcode.cc/openai/v1` | ✅ вместе с `"api": "openai-responses"` (проверено); для Chat это не полный путь |
| `https://api.qcode.cc/api` | ❌ префикс Anthropic Messages, а не путь OpenAI |

Для Responses проверку прошёл и `https://api.qcode.cc/openai`; здесь используется `/openai/v1`, чтобы у обеих записей был общий базовый адрес. В документации также сказано, что протокол переключает только `api`, явно указанный в записи модели.

### CodeBuddy IDE (📄 по официальной документации)

Документация IDE описывает те же пути к файлам и поля для Chat. Страница IDE определяет `apiKey` как «actual key value, not environment variable name», поэтому впишите сам ключ. Запись Chat для IDE:

```json
{
  "models": [
    {
      "id": "deepseek-v4-flash",
      "name": "QCode DeepSeek V4 Flash",
      "vendor": "QCode",
      "url": "https://api.qcode.cc/openai/v1/chat/completions",
      "apiKey": "cr_xxx",
      "maxInputTokens": 128000,
      "maxOutputTokens": 8192,
      "supportsToolCall": true
    }
  ]
}
```

В таблице полей IDE нет поля `api`, так что записи Responses предназначены для CLI. Если IDE и CLI работают с одним `~/.codebuddy/models.json`, вписывайте сам ключ в каждую запись — CLI тоже принимает ключ, записанный напрямую. Официальный совет: не коммитьте `models.json` с настоящим ключом в систему контроля версий и выставьте права на файл 600 (чтение и запись только для владельца).

### Таблица полей

| Поле | Тип | Описание (официальная формулировка) |
|---|---|---|
| `id` | string | Обязательное. Уникальный идентификатор модели |
| `name` | string | Отображаемое имя модели |
| `vendor` | string | Поставщик модели (например, OpenAI, Google) |
| `apiKey` | string | API-ключ. На странице IDE: «actual key value, not environment variable name»; на странице CLI: «supports environment variable references» |
| `maxInputTokens` | number | Максимум входных токенов |
| `maxOutputTokens` | number | Максимум выходных токенов |
| `url` | string | URL эндпоинта API (должен быть полным путём интерфейса, обычно заканчивается на /chat/completions) |
| `supportsToolCall` | boolean | Поддерживаются ли вызовы инструментов |
| `supportsImages` | boolean | Поддерживается ли ввод изображений |
| `supportsReasoning` | boolean | Поддерживается ли режим рассуждений |

На странице CLI есть ещё три поля: `api` (протокол запросов; `openai-responses` переключает на Responses API), `temperature` (температура сэмплирования, 0-2) и `relatedModels` (какой id модели использовать в сценариях вроде lite и reasoning). Поле верхнего уровня `availableModels` — массив строк: в выпадающем списке появляются только перечисленные в нём id, а пустой или отсутствующий массив показывает все модели.

### Ссылки на переменные окружения через `${VAR_NAME}` (CLI)

На странице CLI сказано, что поля `apiKey` и `url` поддерживают синтаксис ссылок `${VAR_NAME}`; ссылка в `apiKey` из примера выше прошла проверку. Официальные примечания: переменные окружения подставляются при запуске CLI; если переменной нет, остаётся исходный плейсхолдер, и вызов API завершается ошибкой.

### Горячая перезагрузка

По документации, файлы конфигурации поддерживают горячую перезагрузку: изменения обоих `models.json` выше подхватываются автоматически с задержкой (debounce) в 1 секунду.

## Переменные окружения CLI

Официальная страница переменных окружения перечисляет три переменные, относящиеся к сторонним моделям:

| Переменная | Официальное описание |
|---|---|
| `CODEBUDDY_API_KEY` | API-ключ для вызовов API модели. В неинтерактивном режиме (-p) всегда используется этот ключ |
| `CODEBUDDY_BASE_URL` | Переопределяет адрес эндпоинта API, обычно вместе с `CODEBUDDY_API_KEY` |
| `CODEBUDDY_MODEL` | Переопределяет модель агента по умолчанию |

На 2026-11-10 проверено на CodeBuddy Code CLI 2.182.0: `CODEBUDDY_BASE_URL` принимает базовый адрес OpenAI Chat Completions, и CLI дописывает к нему `/chat/completions`. Укажите `https://api.qcode.cc/openai/v1` и выберите модель GPT или китайскую модель; `models.json` для этого пути не нужен:

```bash
export CODEBUDDY_BASE_URL="https://api.qcode.cc/openai/v1"
export CODEBUDDY_API_KEY="cr_xxx"
codebuddy -p "Reply with exactly: OK" --model deepseek-v4-flash
```

Оставляйте в `CODEBUDDY_BASE_URL` именно `/openai/v1`: с `https://api.qcode.cc/api` запрос уходит на `/api/chat/completions`, и QCode отвечает HTTP 400.

## Проверка

Сначала убедитесь, что путь OpenAI в QCode доступен из вашей сети (та же проверка, что в разделе [Точки доступа и форматы API](/docs/getting-started/endpoints-and-api-paths)):

```bash
KEY="cr_xxx"

curl -s -o /dev/null -w '%{http_code}\n' -X POST \
  https://api.qcode.cc/openai/v1/chat/completions \
  -H "Authorization: Bearer $KEY"
# 400 = path and key both work (empty body is expected)
# 401 = bad key; 404 = wrong path prefix
```

Затем:

1. CLI: выполните тесты `codebuddy -p` выше; ответ `OK` означает успех. Для интерактивной работы запустите `codebuddy --model deepseek-v4-flash`.
2. IDE: откройте выпадающий список моделей. По документации, модели из `models.json` автоматически получают метку `custom`, чтобы их было легко найти и отфильтровать. Отправьте новой модели короткое сообщение.
3. Введите ключ на [probe.qcode.cc](https://probe.qcode.cc) — там видны запрос и модель, которая ответила.

## Решение проблем

### Конфигурация не применяется

Официальный чек-лист: проверьте корректность JSON; проверьте путь к файлу; посмотрите в логах, загрузилась ли конфигурация; убедитесь, что API-ключ в переменной окружения задан. У горячей перезагрузки задержка 1 секунда, поэтому убедитесь, что файл действительно сохранён на диск.

### Модели нет в выпадающем списке

По документации: проверьте, что ID модели указан в `availableModels`, и что конфигурация `models` корректна. `availableModels` уровня проекта полностью заменяет пользовательский, без слияния. Официальный раздел о неполадках называет обязательными полями «id, name, provider», а таблица полей отмечает обязательным только `id` и называет поле `vendor`; если заполнить `id`, `name` и `vendor`, выполнены оба варианта.

### HTTP 404

`url` записи Chat не доходит до `/chat/completions` или равен `https://api.qcode.cc/api`. Записи Chat всегда используют полный путь `https://api.qcode.cc/openai/v1/chat/completions`; только записи с `"api": "openai-responses"` заканчиваются на `/openai/v1`.

### HTTP 400 `model_not_available_on_endpoint`

id вида `claude-…` ушёл на путь OpenAI — например, из записи `models.json` или через `CODEBUDDY_BASE_URL`, равный `https://api.qcode.cc/api`. Модели Claude доступны только через эндпоинт Anthropic; используйте здесь GPT или китайскую модель либо перейдите на инструмент вроде [Claude Code](/docs/getting-started/installation). Эта ошибка не означает, что ключ неверен.

### HTTP 401

Ключ должен начинаться с `cr_` и не содержать пробелов. При ссылке на переменную окружения проверьте, что она действительно экспортирована: по документации, отсутствующая переменная оставляет исходный плейсхолдер, и в качестве ключа уходит буквальная строка `${QCODE_API_KEY}`.

### Нужно ли входить в аккаунт Tencent?

Для этих моделей — нет. В проверке на 2.182.0 `codebuddy -p` ответил и через `models.json`, и через `CODEBUDDY_BASE_URL` без какого-либо входа.

### Отправляет ли кастомная модель заголовки идентификации платформы Tencent?

В официальных примечаниях к выпуску CLI v2.180.0 сказано, что кастомные модели больше не передают заголовки идентификации платформы: когда кастомная модель подключается напрямую к стороннему эндпоинту, идентификационные данные в настроенный вами сервис не отправляются.

## Связанные материалы

- [Настройка своей модели WorkBuddy](/docs/ide/workbuddy) — офисный агент той же команды, тоже на OpenAI Chat Completions
- [ZCode: свой провайдер](/docs/ide/zcode) — свои провайдеры на протоколах Anthropic и OpenAI, включая Claude
- [Точки доступа и форматы API](/docs/getting-started/endpoints-and-api-paths) — три протокола, три домена, карта `BASE_URL`
- [Китайские модели](/docs/usage/cn-models) — id моделей GLM / Kimi / DeepSeek / Qwen
- [Обзор совместимости инструментов](/docs/ide/tool-compatibility) — протоколы по инструментам и доступность Claude
- Актуальные id и цены: [qcode.cc/models](https://qcode.cc/models)