# راه‌اندازی ارائه‌دهنده سفارشی ZCode (دسکتاپ و CLI)

> **آخرین بازبینی**: 2026-11-10 · 📄 طبق مستندات رسمی (ZCode دسکتاپ v3.17.2، مورخ 2026-11-03 در README و تغییرات) · ✅ اتصال 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 آن، «یک فضای کار کدنویسی با هوش مصنوعی با رابط‌های دسکتاپ، مرورگر و ترمینال». Apache-2.0، از Z.ai (Zhipu)؛ مخزن [zai-org/ZCode](https://github.com/zai-org/ZCode) |
| مدل‌های قابل استفاده | Claude ✅ · GPT ✅ · GLM / Kimi / DeepSeek / Qwen ✅ · Gemini ❌ (QCode در حال حاضر مدل‌های Gemini را ارائه نمی‌دهد) |
| 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`) |
| مستندات رسمی | [اتصال مدل‌ها](https://zcode.z.ai/en/docs/configuration) · [نصب](https://zcode.z.ai/en/docs/install) · [پرسش‌های متداول](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 را انتخاب کنید | پلن حساب کاربری: «اگر حساب کاربری شما GLM Coding Plan داشته باشد، ZCode مستقیماً از پلن و سهمیه همان حساب استفاده می‌کند.» |
| کلید API در صفحه ارائه‌دهنده Z.ai / BigModel | آن صفحه را به حالت کلید API تغییر دهید؛ فیلد **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) مراجعه کنید):

| پروتکل | QCode Base URL | مدل‌ها | CLI `api.type` |
|---|---|---|---|
| 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` |

ZCode خودش مسیر API را اضافه می‌کند. در سورس CLI (`normalizeAnthropicBaseURL`)، یک Anthropic Base URL که به `/v1` ختم نشود، `/v1` می‌گیرد و سپس SDK مسیر `/messages` را اضافه می‌کند؛ بنابراین `https://api.qcode.cc/api` به `/api/v1/messages` می‌رسد. برای دو نوع OpenAI، مسیر `/chat/completions` یا `/responses` را به Base URL اضافه می‌کند؛ به همین دلیل هر دو مقدار به `/openai/v1` ختم می‌شوند. اسلش انتهایی `/` را اضافه نکنید. همان کلید روی `us.qcode.cc` و `asia.qcode.cc` کار می‌کند؛ میزبان را عوض کنید و مسیر را نگه دارید.
## اپلیکیشن دسکتاپ (📄 طبق مستندات رسمی)

مراحل زیر بر اساس مستندات رسمی نسخه v3.17.2 است. همان آدرس‌های QCode در آزمون ZCode CLI پذیرفته شدند؛ در اپلیکیشن دسکتاپ، نخستین پیام آزمایشی شما اتصال را تأیید می‌کند.

### نصب

صفحه نصب رسمی می‌گوید ZCode «از macOS (Apple Silicon / Intel)، Windows (x64 / ARM64) و Linux (x64، ARM64، AppImage، DEB، RPM) پشتیبانی می‌کند» و v3.17.2 را آخرین نسخه علامت می‌زند.

- macOS: فایل `ZCode.dmg` دانلودشده را باز کنید و ZCode.app را به پوشه Applications بکشید. اگر 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 چگونه بین دو نقطه پایانی یک ارائه‌دهنده انتخاب می‌کند. بنابراین این صفحه برای هر پروتکل یک ارائه‌دهنده در نظر می‌گیرد:

| نام ارائه‌دهنده | فیلد نقطه پایانی | مقدار | شناسه‌های مدل (نمونه‌ها) |
|---|---|---|---|
| `QCode Claude` | نقطه پایانی Anthropic | `https://api.qcode.cc/api` | `claude-sonnet-5-5`، `claude-opus-5-5`، `claude-haiku-5-5` |
| `QCode OpenAI` | نقطه پایانی OpenAI | `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: `https://api.qcode.cc/api` (عبارت رسمی چنین است: «Choose the vendor Base URL from the dropdown, or enter the API base URL manually»؛ آن را دستی وارد کنید)
   - کلید API: کلید QCode شما (با `cr_` شروع می‌شود)
4. روی **Add Model** کلیک کنید و هر شناسه مدل را وارد کنید، مثلاً `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 به‌صورت `https://api.qcode.cc/openai/v1`، همان کلید و مدل‌هایی مانند `gpt-6.1-sol` و `deepseek-v4-flash` تکرار کنید.

شناسه‌های مدل فهرست‌شده در [qcode.cc/models](https://qcode.cc/models) را عیناً و حرف‌به‌حرف استفاده کنید؛ نرخ‌های هر مدل نیز همان‌جا فهرست شده است. مدل‌های چینی روی نقطه پایانی Anthropic هم کار می‌کنند اگر ترجیح می‌دهید آن‌ها را در `QCode Claude` نگه دارید. مستندات دسکتاپ نقاط پایانی Anthropic و OpenAI را نام می‌برد؛ گزینه جداگانه‌ای برای Responses فهرست نمی‌کند، پس برای Responses از CLI زیر استفاده کنید.

### فایل پیکربندی دسکتاپ

پرسش‌های متداول رسمی، `~/.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.» ارائه‌دهنده‌ها را در رابط کاربری تنظیم کنید، نه با ویرایش دستی فایل. پرسش‌های متداول همچنین می‌گوید متغیرهای محیطی ترمینال و تنظیمات مدل دسکتاپ دو نقطه ورود جداگانه‌اند و پیکربندی به‌طور خودکار همگام‌سازی نمی‌شود.
## 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` و شناسه مدل را تغییر دهید (هم در `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` و جزئیات اجرا را برمی‌گرداند؛ مقدار `ready` در `response` یعنی ارائه‌دهنده کار می‌کند. همیشه `--mode` را بدهید: بدون آن، `--prompt` در حالت `yolo` اجرا می‌شود که فرمان‌ها را اجرا و فایل‌ها را ویرایش می‌کند. اجرای `zcode` بدون آرگومان، TUI تعاملی را آغاز می‌کند.
## بررسی

1. دسکتاپ: مدل ارائه‌دهنده جدید را از انتخاب‌گر مدل در جعبه چت انتخاب کنید و یک دستور آزمایشی کوتاه بفرستید، همان‌طور که صفحه رسمی توصیه می‌کند («یک دستور آزمایشی کوتاه بفرستید»).
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"}]}'
```

## عیب‌یابی

| نشانه | علت | رفع |
|---|---|---|
| دسکتاپ: اتصال در حال بارگذاری می‌ماند | پرسش‌های متداول رسمی: دستگاه نمی‌تواند به سرویس مدل دسترسی پیدا کند، یا کلید سهمیه یا دسترسی به مدل ندارد | شبکه را بررسی کنید، سپس کلید و شناسه مدل را بررسی کنید |
| `model_not_available_on_endpoint` | یک شناسه `claude-...` روی نقطه پایانی OpenAI یا `api.type` مربوط به OpenAI اضافه شده است | شناسه‌های Claude را روی نقطه پایانی Anthropic قرار دهید (`anthropic-messages` در CLI) |
| 404 | `/` انتهایی، یا یک Base URL مربوط به OpenAI بدون `/v1` | از مقادیر بالا دقیقاً استفاده کنید و آن‌ها را با دستورهای curl مقایسه کنید |
| CLI کلید یا آدرس شما را نادیده می‌گیرد | 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 دیده شده است؛ فراخوانی‌ها از طریق ارائه‌دهنده خودتان همچنان موفق‌اند و اجراهای بعدی آن را به‌عنوان ردشده گزارش می‌کنند | اقدامی لازم نیست |
| بالاترین سطح تفکر خطای پارامتر 400 برمی‌گرداند | رسمی: برخی استقرارهای شخص ثالث فقط تا `xhigh` را می‌پذیرند، در حالی که ZCode برای DeepSeek V4 مقدار `max` را می‌فرستد | به‌جای آن `high` را انتخاب کنید: «انتخاب high به‌جای آن به‌خوبی کار می‌کند.» |
| هیچ سطح تفکر ریزدانه‌ای برای یک مدل وجود ندارد | رسمی: ZCode هیچ نگاشت سطح شناخته‌شده‌ای برای آن مدل ندارد؛ «تنظیم از دست نرفته است» | از سوییچ ساده روشن/خاموش استفاده کنید |
| دسکتاپ: `reasoning_effort` در `options` اثری ندارد | رسمی: سایر کلیدها «بی‌صدا نادیده گرفته می‌شوند» | از سطوح موجود در UI استفاده کنید |
| تصاویر حذف می‌شوند | مثال رسمی: GLM-5.2 روی یک نقطه پایانی سازگار با OpenAI Chat «به‌عنوان مدلی که از ورودی تصویر پشتیبانی نمی‌کند در نظر گرفته می‌شود»؛ نقطه پایانی یا پروتکل دیگر می‌تواند متفاوت باشد | قابلیت تصویر مدل را در پیکربندی مدل آن اعلام کنید، یا از تصاویر با آن مدل پرهیز کنید |

ZCode سطح تفکر انتخاب‌شده را برای نقطه پایانی تبدیل می‌کند: «نقاط پایانی سازگار با OpenAI از فیلد سطح بالای reasoning_effort استفاده می‌کنند، در حالی که نقاط پایانی سازگار با Anthropic از thinking / effort استفاده می‌کنند.»

## محدودیت‌های شناخته‌شده

- بخش دسکتاپ از مستندات رسمی برای v3.17.2 پیروی می‌کند؛ نام‌های منو می‌توانند بین نسخه‌ها تغییر کنند. بخش CLI با 0.17.1 و یک مدل به‌ازای هر پروتکل آزمایش شده است.
- صفحه رسمی می‌گوید افزودن پارامترهای سفارشی درخواست برای مدل‌های شخص ثالث هنوز پشتیبانی نمی‌شود.
- مستندات دسکتاپ نقاط پایانی Anthropic و OpenAI را نام می‌برد؛ Responses از طریق `openai-responses` در CLI در دسترس است. QCode فعلاً مدل‌های Gemini را ارائه نمی‌دهد.
- 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) — شناسه‌ها و مسیرهای GLM / Kimi / DeepSeek / Qwen