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

ZCode را به‌عنوان ارائه‌دهنده سفارشی به QCode.cc متصل کنید: مراحل دسکتاپ طبق مستندات رسمی، و ZCode CLI 0.17.1 آزمایش‌شده روی Anthropic، OpenAI Chat و Responses.

به کلید API نیاز دارید؟ ثبت‌نام ←·نقاط پایانی و Base URL ←

آخرین بازبینی: 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 نیست. مراحل دسکتاپ از مستندات رسمی پیروی می‌کنند.

نگاه کلی¶

کدام پروتکل¶

ZCode سه روش برای دریافت مدل دارد و تفاوت آن‌ها در این است که سهمیه از کجا می‌آید:

این صفحه روش سوم را پوشش می‌دهد. QCode مدل Claude را فقط روی پروتکل Anthropic و GPT را فقط روی پروتکل‌های OpenAI ارائه می‌دهد؛ GLM، Kimi، DeepSeek و Qwen روی Anthropic و OpenAI Chat کار می‌کنند (به نقاط پایانی و مسیرهای API مراجعه کنید):

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 دانلود کنید.

افزودن QCode به‌عنوان ارائه‌دهنده¶

مستندات ارائه‌دهندگانی را نشان می‌دهد که یک نقطه پایانی را پر می‌کنند و مثالی از DeepSeek که هر دو را پر می‌کند، اما نمی‌گوید ZCode چگونه بین دو نقطه پایانی یک ارائه‌دهنده انتخاب می‌کند. بنابراین این صفحه برای هر پروتکل یک ارائه‌دهنده در نظر می‌گیرد:

1. ZCode را باز کنید، روی نام مدل در کادر چت کلیک کنید، سپس در پایین فهرست روی Manage Models کلیک کنید. این کار Settings -> Model Settings را باز می‌کند. در نخستین اجرا بدون مدل قابل استفاده، گزینه Use API Key در صفحه خوش‌آمدگویی نیز به تنظیمات ارائه‌دهنده مدل می‌رسد.
2. در پایین فهرست ارائه‌دهنده‌ها در سمت چپ روی Add Provider کلیک کنید.

3. برای ارائه‌دهنده نخست:

4. نام: QCode Claude (نام را خودتان انتخاب می‌کنید؛ صفحه رسمی نام‌هایی مانند claude یا deepseek را پیشنهاد می‌کند)

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

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

بررسی¶

1. دسکتاپ: مدل ارائه‌دهنده جدید را از انتخاب‌گر مدل در جعبه چت انتخاب کنید و یک دستور آزمایشی کوتاه بفرستید، همان‌طور که صفحه رسمی توصیه می‌کند («یک دستور آزمایشی کوتاه بفرستید»).
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 از فیلد سطح بالای 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 — جدول پروتکل × خانواده مدل
• مرور سازگاری ابزارها — کدام ابزارها با کدام پروتکل صحبت می‌کنند
• Kimi Code CLI — یک عامل ترمینال دیگر با ارائه‌دهنده‌های Anthropic، OpenAI Chat و Responses
• MiniMax Code — برنامه دسکتاپ و CLI mcode با همان سه قالب API
• DeepSeek Harness (dsh) — یک هارنس عامل دیگر با فرم مدل سفارشی
• مدل‌های چینی — شناسه‌ها و مسیرهای GLM / Kimi / DeepSeek / Qwen

سازمانی ←