# ZCode: свой провайдер (десктоп и CLI)

> **Последняя проверка**: 2026-11-10 · 📄 По официальной документации (десктопная версия ZCode v3.17.2, в README и changelog датирована 2026-11-03) · ✅ Подключение к QCode проверено на ZCode CLI 0.17.1 (2026-11-10)

Да, в ZCode можно работать со своим API-ключом и своим эндпоинтом. В десктопном приложении он добавляется через **Add Provider**, а открытый ZCode CLI читает его из `~/.zcode/v2/provider_config.json`. На 2026-11-10 проверено на ZCode CLI 0.17.1: QCode работает по всем трём протоколам (Anthropic Messages, OpenAI Chat Completions, OpenAI Responses), входить в аккаунт Z.ai или BigModel не нужно. Шаги для десктопа описаны по официальной документации.

## Кратко

| Пункт | Подробности |
|---|---|
| Что это | По словам README, «an AI coding workspace with desktop, browser, and terminal interfaces». Проект Z.ai (Zhipu) под Apache-2.0, репозиторий [zai-org/ZCode](https://github.com/zai-org/ZCode) |
| Доступные модели | Claude ✅ · GPT ✅ · GLM / Kimi / DeepSeek / Qwen ✅ · Gemini ❌ (модели Gemini QCode пока не предоставляет) |
| Anthropic Messages | `https://api.qcode.cc/api` (ZCode сам добавляет `/v1/messages`) · ✅ проверено в CLI |
| OpenAI Chat Completions | `https://api.qcode.cc/openai/v1` · ✅ проверено в CLI |
| OpenAI Responses | `https://api.qcode.cc/openai/v1` · ✅ проверено в CLI; в документации десктопа этого протокола нет |
| Десктоп | **Manage Models** → **Settings -> Model Settings** → **Add Provider**; файл `~/.zcode/v2/config.json` |
| ZCode CLI | сборка из исходников; файл `~/.zcode/v2/provider_config.json` (`access.apiKey`, `api.type`, `api.baseUrl`) |
| Официальная документация | [Connect Models](https://zcode.z.ai/en/docs/configuration) · [Install](https://zcode.z.ai/en/docs/install) · [FAQ](https://zcode.z.ai/en/docs/qa) · [руководство по CLI](https://github.com/zai-org/ZCode/blob/main/apps/zcode-cli/docs/usage/README.md) |

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

Получить модель в ZCode можно тремя способами, и они различаются тем, откуда списывается квота:

| Способ | Что сделать | Где учитывается расход |
|---|---|---|
| Вход через аккаунт | На экране приветствия выбрать Z.ai или BigModel | Тариф аккаунта: «If your account has a GLM Coding Plan, ZCode uses the plan and quota from that account directly.» |
| API-ключ на странице провайдера Z.ai / BigModel | Переключить страницу в режим API Key; появятся поля **OpenAI Base URL** и **Anthropic Base URL** | Введённый ключ Z.ai или BigModel |
| Свой провайдер | **Add Provider** (десктоп) или `provider_config.json` (CLI) со своим эндпоинтом и ключом | Сервис, на который вы указали, здесь — QCode |

Эта статья — о третьем способе. В QCode модели Claude доступны только по протоколу Anthropic, GPT — только по протоколам OpenAI; GLM, Kimi, DeepSeek и Qwen работают и через Anthropic, и через OpenAI Chat (см. [Точки доступа и форматы API](/docs/getting-started/endpoints-and-api-paths)):

| Протокол | Base URL в QCode | Модели | `api.type` в CLI |
|---|---|---|---|
| Anthropic Messages | `https://api.qcode.cc/api` | Claude, GLM / Kimi / DeepSeek / Qwen | `anthropic-messages` |
| OpenAI Chat Completions | `https://api.qcode.cc/openai/v1` | GPT, GLM / Kimi / DeepSeek / Qwen | `openai-chat-completions` |
| OpenAI Responses | `https://api.qcode.cc/openai/v1` | GPT | `openai-responses` |

Путь API ZCode добавляет сам. В исходниках CLI (`normalizeAnthropicBaseURL`) к Base URL для Anthropic, который не заканчивается на `/v1`, дописывается `/v1`, а затем SDK добавляет `/messages`, поэтому `https://api.qcode.cc/api` ведёт на `/api/v1/messages`. Для двух типов OpenAI к Base URL сразу дописывается `/chat/completions` или `/responses` — поэтому оба значения заканчиваются на `/openai/v1`. Не ставьте `/` в конце. Тот же ключ работает на `us.qcode.cc` и `asia.qcode.cc`: замените хост, путь оставьте прежним.

## Десктопное приложение (📄 по официальной документации)

Шаги ниже соответствуют официальной документации для v3.17.2. Те же адреса QCode прошли проверку в ZCode CLI; в десктопе подключение подтверждает ваше первое тестовое сообщение.

### Установка

На официальной странице установки сказано: ZCode «Supports macOS (Apple Silicon / Intel), Windows (x64 / ARM64), and Linux (x64, ARM64, AppImage, DEB, RPM).», а v3.17.2 отмечена как последняя версия.

- macOS: откройте скачанный `ZCode.dmg` и перетащите ZCode.app в папку «Программы». Если macOS сообщает, что приложение повреждено, официальное решение — `xattr -dr com.apple.quarantine /Applications/ZCode.app`.
- Windows: скачайте установщик, запустите его двойным щелчком и следуйте мастеру.
- Linux: скачайте `.AppImage`, `.deb` или `.rpm`; для AppImage выполните `chmod +x ZCode-*.AppImage`.

Установщики скачивайте на [zcode.z.ai](https://zcode.z.ai/en/docs/install).

### Добавить QCode как провайдера

В документации есть примеры провайдеров с одним эндпоинтом и пример DeepSeek, где заполнены оба, но не сказано, как ZCode выбирает между двумя эндпоинтами одного провайдера. Поэтому здесь используется по одному провайдеру на протокол:

| Имя провайдера | Поле эндпоинта | Значение | ID моделей (примеры) |
|---|---|---|---|
| `QCode Claude` | Anthropic endpoint | `https://api.qcode.cc/api` | `claude-sonnet-5-5`, `claude-opus-5-5`, `claude-haiku-5-5` |
| `QCode OpenAI` | OpenAI endpoint | `https://api.qcode.cc/openai/v1` | `gpt-6.1-sol`, `deepseek-v4-flash`, `glm-5.3`, `kimi-k3`, `qwen3.8-max` |

1. Откройте ZCode, нажмите на название модели в поле чата, затем на **Manage Models** внизу списка. Откроется **Settings -> Model Settings**. Если при первом запуске доступной модели нет, к настройкам провайдеров ведёт и кнопка **Use API Key** на экране приветствия.
2. Нажмите **Add Provider** внизу списка провайдеров слева.
3. Первый провайдер:
   - Имя: `QCode Claude` (имя выбираете сами; на официальной странице в примерах — claude или deepseek)
   - Anthropic endpoint: `https://api.qcode.cc/api` (официальная формулировка — «Choose the vendor Base URL from the dropdown, or enter the API base URL manually»; введите адрес вручную)
   - API Key: ваш ключ QCode (начинается с `cr_`)
4. Нажмите **Add Model** и введите ID моделей по одному, например `claude-sonnet-5-5`. Официальный текст: «click Add Model and enter the model IDs supported by that service».
5. Включите переключатель («Turn on the enable switch to start using it») и сохраните.
6. Повторите для имени `QCode OpenAI`: OpenAI endpoint `https://api.qcode.cc/openai/v1`, тот же ключ и модели вроде `gpt-6.1-sol` и `deepseek-v4-flash`.

ID моделей берите со страницы [qcode.cc/models](https://qcode.cc/models) символ в символ; там же указаны цены по моделям. Китайские модели работают и через эндпоинт Anthropic, так что их можно держать в `QCode Claude`. Документация десктопа называет эндпоинты Anthropic и OpenAI, отдельного пункта для Responses в ней нет — для Responses используйте CLI ниже.

### Файл конфигурации десктопа

Официальный FAQ называет `~/.zcode/v2/config.json` файлом, в котором хранятся «Model provider setup (API keys, base URLs, model lists)», поэтому обращайтесь с ним как с секретом и не коммитьте его. Про этот файл на странице есть одно правило: «a provider's options only recognizes connection settings such as apiKey, baseURL, apiKeyRequired, and headers; any other keys added by hand (e.g. reasoning_effort, vl_high_resolution_images) are silently ignored and never written into the request body.» Настраивайте провайдеров в интерфейсе, а не правкой файла. В FAQ также сказано, что переменные окружения терминала и настройка моделей в десктопе — разные точки входа и автоматически не синхронизируются.

## ZCode CLI (✅ проверено 2026-11-10)

На 2026-11-10 проверено на ZCode CLI 0.17.1: все три протокола QCode работают через `~/.zcode/v2/provider_config.json`, `zcode login` не нужен.

### Сборка из исходников

CLI распространяется в виде исходного кода: [быстрый старт](https://github.com/zai-org/ZCode/blob/main/apps/zcode-cli/docs/usage/01-quickstart.md) собирает его из репозитория. Нужны Git, Node.js 24.14.0 и pnpm 10.33.2 (точные версии — в `mise.toml` репозитория). Команды выполняются в корне репозитория:

```sh
git clone https://github.com/zai-org/ZCode.git
cd ZCode
pnpm install --frozen-lockfile
pnpm --filter @zcode/cli... build
node apps/zcode-cli/packages/cli/dist/zcode.cjs --version
node apps/zcode-cli/packages/cli/dist/zcode.cjs doctor --json
```

В командах ниже `zcode` означает `node /absolute/path/to/zcode.cjs`; файлы, которые сборка кладёт рядом, не удаляйте.

### Записать provider_config.json

Сохраните это как `~/.zcode/v2/provider_config.json` и замените `cr_xxx` своим ключом QCode. Это настройка Anthropic из проверки:

```json
{
  "schemaVersion": 1,
  "config": {
    "providerConfigRules": {
      "providerRules": [
        {
          "providerId": "qcode",
          "providerName": "QCode",
          "config": {
            "group": "standard-personal",
            "access": { "type": "api-key", "apiKey": "cr_xxx" },
            "api": {
              "type": "anthropic-messages",
              "baseUrl": "https://api.qcode.cc/api"
            },
            "personalModelIds": ["claude-haiku-5-5"]
          }
        }
      ]
    },
    "modelConfigRules": {
      "providerModelRules": [],
      "manualProviderModelRules": []
    },
    "defaultModelSelection": {
      "providerId": "qcode",
      "modelId": "claude-haiku-5-5"
    }
  }
}
```

Для другого протокола измените `api.type`, `api.baseUrl` и ID модели (и в `personalModelIds`, и в `defaultModelSelection.modelId`):

| Протокол | `api.type` | `api.baseUrl` | Проверенная модель |
|---|---|---|---|
| Anthropic Messages | `anthropic-messages` | `https://api.qcode.cc/api` | `claude-haiku-5-5` ✅ |
| OpenAI Chat Completions | `openai-chat-completions` | `https://api.qcode.cc/openai/v1` | `deepseek-v4-flash` ✅ |
| OpenAI Responses | `openai-responses` | `https://api.qcode.cc/openai/v1` | `gpt-6.1-terra` ✅ |

Два момента из официального руководства по CLI:

- Поле называется `api.baseUrl` и пишется иначе, чем `options.baseURL` в файле десктопа; CLI читает `provider_config.json`, а не `~/.zcode/v2/config.json`.
- Руководство не обещает подстановку `${ENV}` в `apiKey`, поэтому ключ хранится в файле открытым текстом. Ограничьте права на файл и не добавляйте его в Git:

```sh
chmod 600 ~/.zcode/v2/provider_config.json
```

### Неинтерактивная проверка

```sh
zcode --prompt "Reply with one word: ready. Do not call tools." \
  --cwd /path/to/project --mode plan --json --no-color
```

`--json` возвращает `sessionId`, `response` и сведения о запуске; `response` со значением `ready` означает, что провайдер работает. Всегда указывайте `--mode`: без него `--prompt` работает в режиме `yolo`, то есть сразу выполняет команды и меняет файлы. `zcode` без аргументов запускает интерактивный TUI.

## Проверка

1. Десктоп: выберите модель нового провайдера в селекторе моделей в поле чата и отправьте короткую тестовую инструкцию, как советует официальная страница («send a short test instruction»).
2. CLI: выполните проверку с `--prompt` выше.
3. Откройте [probe.qcode.cc](https://probe.qcode.cc), введите ключ QCode и убедитесь, что запрос с этой моделью появился.
4. Проверить ключ и путь без ZCode:

```bash
KEY="cr_your_key"

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

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

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

| Симптом | Причина | Что делать |
|---|---|---|
| Десктоп: подключение бесконечно грузится | Официальный FAQ: машина не может достучаться до сервиса моделей или у ключа нет квоты либо доступа к модели | Проверьте сеть, затем ключ и ID модели |
| `model_not_available_on_endpoint` | ID `claude-...` добавлен на эндпоинт OpenAI или в `api.type` типа OpenAI | Размещайте ID Claude на эндпоинте Anthropic (`anthropic-messages` в CLI) |
| 404 | `/` в конце или Base URL для OpenAI без `/v1` | Используйте значения выше без изменений и сравните с командами curl |
| CLI не использует ваш ключ или адрес | Он читает `provider_config.json` с `api.baseUrl`, а не десктопный `config.json` | Правьте `~/.zcode/v2/provider_config.json` |
| CLI: адрес QCode в `ZCODE_BASE_URL` не действует | Официально: `ZCODE_BASE_URL` относится к сервисному эндпоинту продукта, а не к API модели | Укажите адрес в `api.baseUrl` |
| CLI: `${QCODE_API_KEY}` в `apiKey` не подставляется | Официально: подстановка `${ENV}` в `apiKey` не гарантируется | Впишите сам ключ и выполните `chmod 600` для файла |
| При первом запуске CLI выводит сообщение, что обновить «ZCode Built-in» не удалось | Замечено в 0.17.1; вызовы через ваш провайдер проходят, при следующих запусках выводится skipped | Ничего делать не нужно |
| Верхний уровень размышлений даёт ошибку параметра 400 | Официально: некоторые сторонние развёртывания принимают максимум `xhigh`, а ZCode отправляет `max` для DeepSeek V4 | Выберите `high`: «Picking high instead works fine.» |
| У модели нет детальных уровней размышлений | Официально: ZCode не знает соответствия уровней для этой модели; «the setting has not been lost» | Пользуйтесь простым переключателем вкл./выкл. |
| Десктоп: `reasoning_effort` в `options` ни на что не влияет | Официально: прочие ключи «silently ignored» | Используйте уровни в интерфейсе |
| Изображения отбрасываются | Официальный пример: GLM-5.2 через OpenAI Chat-совместимый эндпоинт «is treated as not supporting image input»; на другом эндпоинте или протоколе результат может отличаться | Укажите поддержку изображений в конфигурации модели или не отправляйте изображения этой модели |

ZCode преобразует выбранный уровень размышлений под эндпоинт: «OpenAI-compatible endpoints use the top-level reasoning_effort field, while Anthropic-compatible endpoints use thinking / effort.»

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

- Раздел о десктопе опирается на официальную документацию к v3.17.2; названия пунктов меню могут меняться между версиями. Раздел о CLI проверен на 0.17.1, по одной модели на протокол.
- По официальной странице, добавлять собственные параметры запроса для сторонних моделей пока нельзя.
- Документация десктопа называет эндпоинты Anthropic и OpenAI; Responses доступен через `openai-responses` в CLI. Модели Gemini QCode пока не предоставляет.
- CLI: ключ хранится открытым текстом в `provider_config.json`, а `--prompt` без `--mode` работает в режиме `yolo`.

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

- [Точки доступа и форматы API](/docs/getting-started/endpoints-and-api-paths) — таблица «протокол × семейство моделей»
- [Обзор совместимости инструментов](/docs/ide/tool-compatibility) — какой инструмент какой протокол поддерживает
- [Настройка Kimi Code CLI](/docs/ide/kimi-code) — ещё один терминальный агент с провайдерами Anthropic, OpenAI Chat и Responses
- [Настройка MiniMax Code](/docs/ide/minimax-code) — десктоп и CLI `mcode` с теми же тремя форматами API
- [DeepSeek Harness (dsh)](/docs/ide/deepseek-harness) — ещё одна оболочка для агентов с формой своей модели
- [Китайские модели](/docs/usage/cn-models) — ID и пути GLM / Kimi / DeepSeek / Qwen