# إعداد مزوّد مخصص لـ ZCode (سطح المكتب وCLI)

> **آخر تحقق**: 2026-11-10 · 📄 وفق الوثائق الرسمية (ZCode desktop 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)):

| البروتوكول | 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` |

يضيف ZCode مسار API بنفسه. في مصدر CLI (`normalizeAnthropicBaseURL`)، يُضاف `/v1` إلى Base URL الخاص بـ Anthropic الذي لا ينتهي بـ `/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، وانقر اسم النموذج في مربع المحادثة، ثم **إدارة النماذج** أسفل القائمة. يفتح ذلك **الإعدادات -> إعدادات النموذج**. عند أول تشغيل دون نموذج صالح للاستخدام، يؤدي **استخدام مفتاح API** في شاشة الترحيب أيضًا إلى إعدادات مزوّد النموذج.
2. انقر **إضافة مزوّد** أسفل قائمة المزوّدين على اليسار.
3. للمزوّد الأول:
   - الاسم: `QCode Claude` (الاسم متروك لاختيارك؛ وتقترح الصفحة الرسمية أسماء مثل claude أو deepseek)
   - نقطة نهاية Anthropic: `https://api.qcode.cc/api` (الصياغة الرسمية هي «اختر Base URL الخاص بالمورّد من القائمة المنسدلة، أو أدخل Base URL الخاص بـ API يدويًا»؛ أدخله يدويًا)
   - مفتاح API: مفتاح QCode الخاص بك (يبدأ بـ `cr_`)
4. انقر **إضافة نموذج** وأدخل معرّف كل نموذج، على سبيل المثال `claude-sonnet-5-5`. النص الرسمي: «انقر إضافة نموذج وأدخل معرّفات النماذج التي تدعمها تلك الخدمة».
5. شغّل مفتاح التفعيل («شغّل مفتاح التفعيل لبدء استخدامه») واحفظ.
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 منفصلًا، لذا استخدم CLI أدناه من أجل Responses.

### ملف إعدادات سطح المكتب

تدرج الأسئلة الشائعة الرسمية `~/.zcode/v2/config.json` بوصفه الملف الذي يحوي «إعداد مزوّد النموذج (مفاتيح API، وعناوين Base URL، وقوائم النماذج)»، لذا تعامل معه بوصفه سرًّا ولا تُضمّنه في commit. وتوثّق الصفحة قاعدة واحدة بشأنه: «لا يتعرّف خيار options الخاص بالمزوّد إلا على إعدادات الاتصال مثل apiKey وbaseURL وapiKeyRequired وheaders؛ وأي مفاتيح أخرى تُضاف يدويًا (مثل reasoning_effort وvl_high_resolution_images) تُتجاهل بصمت ولا تُكتب أبدًا في جسم الطلب.» أعدّ المزوّدين في واجهة المستخدم بدلًا من تحرير الملف يدويًا. تذكر الأسئلة الشائعة أيضًا أن متغيرات بيئة الطرفية وإعداد النموذج في تطبيق سطح المكتب نقطتا إدخال منفصلتان، وأن الإعدادات لا تُزامَن تلقائيًا.
## 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 | `anthropic-messages` | `https://api.qcode.cc/api` | `claude-haiku-5-5` ✅ |
| إكمالات الدردشة من OpenAI | `openai-chat-completions` | `https://api.qcode.cc/openai/v1` | `deepseek-v4-flash` ✅ |
| استجابات OpenAI | `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. سطح المكتب: اختر نموذج المزوّد الجديد من محدّد النموذج في مربع المحادثة وأرسل تعليمة اختبار قصيرة، كما تنصح الصفحة الرسمية («أرسل تعليمة اختبار قصيرة»).
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"}]}'
```

## استكشاف الأخطاء وإصلاحها

| العَرَض | السبب | الإصلاح |
|---|---|---|
| سطح المكتب: يظل Connect قيد التحميل | الأسئلة الشائعة الرسمية: يتعذر على الجهاز الوصول إلى خدمة النموذج، أو لا يملك المفتاح حصة أو صلاحية وصول إلى النموذج | تحقق من الشبكة، ثم من المفتاح ومعرّف النموذج |
| `model_not_available_on_endpoint` | أُضيف معرّف `claude-...` على نقطة نهاية OpenAI أو `api.type` من OpenAI | ضع معرّفات 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؛ تظل الاستدعاءات عبر مزوّدك ناجحة، وتفيد التشغيلات اللاحقة بأنه تم تخطيه | لا حاجة إلى إجراء |
| يعيد أعلى مستوى تفكير خطأ معامل 400 | الوثائق الرسمية: تقبل بعض عمليات النشر من طرف ثالث حتى `xhigh` فقط بينما يرسل ZCode القيمة `max` لـ DeepSeek V4 | اختر `high` بدلًا من ذلك: «اختيار high بدلًا من ذلك يعمل جيدًا.» |
| لا توجد مستويات تفكير دقيقة لنموذج ما | الوثائق الرسمية: ليس لدى ZCode تعيين مستويات معروف لذلك النموذج؛ «لم يُفقد الإعداد» | استخدم مفتاح التبديل البسيط تشغيل/إيقاف |
| سطح المكتب: لا يكون لـ `reasoning_effort` في `options` أي تأثير | الوثائق الرسمية: تُتجاهل المفاتيح الأخرى «بصمت» | استخدم المستويات في واجهة المستخدم |
| تُسقَط الصور | مثال رسمي: يُتعامل مع 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