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

Подключение ZCode к QCode.cc как своего провайдера: десктоп по официальной документации, ZCode CLI 0.17.1 проверен на Anthropic, OpenAI Chat и Responses.

Нужен API-ключ? Зарегистрироваться →·Эндпоинты и Base URL →

Последняя проверка: 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 не нужно. Шаги для десктопа описаны по официальной документации.

Кратко¶

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

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

Эта статья — о третьем способе. В QCode модели Claude доступны только по протоколу Anthropic, GPT — только по протоколам OpenAI; GLM, Kimi, DeepSeek и Qwen работают и через Anthropic, и через OpenAI Chat (см. Точки доступа и форматы API):

Путь 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.

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

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

1. Откройте ZCode, нажмите на название модели в поле чата, затем на Manage Models внизу списка. Откроется Settings -> Model Settings. Если при первом запуске доступной модели нет, к настройкам провайдеров ведёт и кнопка Use API Key на экране приветствия.
2. Нажмите Add Provider внизу списка провайдеров слева.

3. Первый провайдер:

4. Имя: QCode Claude (имя выбираете сами; на официальной странице в примерах — claude или deepseek)

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

ID моделей берите со страницы 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 распространяется в виде исходного кода: быстрый старт собирает его из репозитория. Нужны Git, Node.js 24.14.0 и pnpm 10.33.2 (точные версии — в mise.toml репозитория). Команды выполняются в корне репозитория:

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 из проверки:

{
  "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):

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

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

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

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

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, введите ключ QCode и убедитесь, что запрос с этой моделью появился.
4. Проверить ключ и путь без ZCode:

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"}]}'

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

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 — таблица «протокол × семейство моделей»
• Обзор совместимости инструментов — какой инструмент какой протокол поддерживает
• Настройка Kimi Code CLI — ещё один терминальный агент с провайдерами Anthropic, OpenAI Chat и Responses
• Настройка MiniMax Code — десктоп и CLI mcode с теми же тремя форматами API
• DeepSeek Harness (dsh) — ещё одна оболочка для агентов с формой своей модели
• Китайские модели — ID и пути GLM / Kimi / DeepSeek / Qwen

Enterprise →