# دليل ربط Coze (扣子) بـ QCode

اتبع الخطوات السبع أدناه، وستختار المسار الصحيح بحسب نسخة حساب Coze لديك، وتربط نماذج Claude وGPT والنماذج الصينية من QCode بوكيل Coze أو بسير العمل، ثم تتحقق من سجل الطلبات في لوحة التحكم.


**الإجابة المختصرة**: لا يوفّر Coze مفتاحًا عامًّا باسم «عنوان Base URL للنموذج المخصص» للحسابات الشخصية. **الحسابات الشخصية وحسابات الفرق** تتصل بواجهة QCode مباشرة عبر «إضافة مخصصة» أو «عقدة طلب HTTP في سير العمل»، ويمكنها استدعاء `claude-opus-5-5` (واجهة Anthropic) و`gpt-6.2-sol` (واجهة متوافقة مع OpenAI) في الوقت نفسه؛ أما **مدير النسخة المؤسسية الرائدة** فيستطيع داخل «Coze Code (`code.coze.cn`) ← إدارة المؤسسة ← ربط النماذج ← نموذج مخصص» أن يربط `gpt-6.2-sol` والنماذج الصينية بشكل أصلي، لكن بروتوكول هذا المدخل ثابت على OpenAI Chat Completions و**لا يدعم Claude**.

| مسار الربط | الحساب المناسب | نماذج QCode المتاحة | عنوان الربط | طريقة المصادقة |
|---|---|---|---|---|
| إضافة مخصصة / HTTP في سير العمل (Claude) | كل حسابات Coze | `claude-opus-5-5` وسائر سلسلة Claude | `https://api.qcode.cc/api/v1/messages` | ترويسة `x-api-key: cr_xxxxxxxx` و`anthropic-version: 2023-06-01` |
| إضافة مخصصة / HTTP في سير العمل (GPT / النماذج الصينية) | كل حسابات Coze | `gpt-6.2-sol` والنماذج الصينية | `https://api.qcode.cc/openai/v1/chat/completions` | ترويسة `Authorization: Bearer cr_xxxxxxxx` |
| نموذج مخصص أصلي (خلفية Coze Code) | مدير المؤسسة في النسخة الرائدة فقط | `gpt-6.2-sol` والنماذج الصينية (**لا يدعم Claude**) | `https://api.qcode.cc/openai/v1` (يُضاف `/chat/completions` تلقائيًا) | اختر `Authorization` واملأ `cr_xxxxxxxx` (أو `Header` كبديل) |

تم التحقق في 2026-11-22 · Coze (coze.cn) وCoze Code (code.coze.cn) · دليل نصي منظّم


[Coze (扣子)](https://www.coze.cn) منصّة سحابية لبناء الوكلاء وسير العمل، وتضمّ واجهتين: المنتج الرئيسي «Coze» (`www.coze.cn`) و«Coze Code» (`code.coze.cn`) الموجّه للمؤسسات وإدارة التطوير منخفض الشيفرة. وقبل أن تبدأ، اعرف القيود الأربعة الحقيقية للمنتج حتى لا تبحث في الواجهة مرارًا عن خيارات لا وجود لها:

> **حدود الدعم الحقيقية ونطاق القيود**:
> 1. **تسجيل الدخول إلى حساب Coze إلزامي**: سواء استخدمت نسخة الويب أو نسخة سطح المكتب، يجب تسجيل الدخول إلى حساب منصة Coze برقم الهاتف أو البريد الإلكتروني أو مسح رمز QR، ولا يمكن تجاوز حساب المنصة والاستخدام دون اتصال.
> 2. **«ربط النماذج» الأصلي مقصور على مدير النسخة المؤسسية الرائدة**: بحسب وثائق Coze الرسمية، مدخل «ربط النماذج ← نموذج مخصص» الأصلي **متاح للنسخة المؤسسية الرائدة فقط، ولا يراه ويضبطه إلا المشرف الأعلى للمؤسسة أو المشرف**؛ أما الحسابات الشخصية العادية ومساحات العمل العادية فلا ترى هذا المدخل.
> 3. **النموذج المخصص الأصلي لا يدعم Claude**: بروتوكول API للنموذج المخصص الأصلي في Coze ثابت على OpenAI Chat/completions، ويشترط إلزامًا أن يدعم المزوّد الاستجابة المتدفقة (`stream=true`)، دون أي خيار لبروتوكول Anthropic Messages. ونقطة النهاية المتوافقة مع OpenAI في QCode لا تقبل نماذج Claude، ولذلك فإن `claude-opus-5-5` **لا يمكن استدعاؤه إلا عبر إضافة مخصصة أو طلب HTTP في سير العمل**.
> 4. **حدود قدرات حل الإضافة / سير العمل عبر HTTP**: حين تستدعي الحسابات الشخصية وحسابات الفرق QCode عبر طلب HTTP، يعمل QCode كأداة خارجية للوكيل أو كعقدة معالجة في سير العمل، ولا يمكنه استبدال نموذج التوجيه الأساسي الافتراضي للوكيل، كما يجب انتظار عودة JSON كامل قبل عرض النتيجة (وليس إخراجًا أصليًا حرفًا بحرف).


- **المنصات المدعومة**: واجهة الويب في المتصفح (`www.coze.cn` / `code.coze.cn`)؛ واختياريًا نسخة سطح المكتب لنظامي Windows / macOS
- **مسار الربط**: إضافة مخصصة / طلب HTTP في سير العمل (كل الحسابات)؛ نموذج مخصص أصلي (مدير النسخة المؤسسية الرائدة فقط)
- **تاريخ التحقق من المحتوى**: 2026-11-22
- **الوقت المتوقع**: 10–15 دقيقة
- **ما تحتاج إليه**: حساب Coze مسجّل الدخول؛ ومفتاح API من QCode يبدأ بـ `cr_`



- أن يكون لديك حساب Coze مسجّل وتستطيع الدخول إليه ([www.coze.cn](https://www.coze.cn))؛ وإذا كنت تنوي استخدام النموذج المخصص الأصلي فتأكد أن المؤسسة التي تنتمي إليها هي **النسخة المؤسسية الرائدة**، وأن حسابك الحالي **مشرف أعلى للمؤسسة أو مشرف**، وأنك تستطيع الوصول إلى Coze Code ([code.coze.cn](https://code.coze.cn))
- أن تكون مسجّلًا في QCode.cc ونسخت مفتاح API الذي يبدأ بـ `cr_` من [لوحة التحكم](https://qcode.cc/ar/dashboard). ليس لديك حساب بعد؟ [أنشئ حساب QCode](https://qcode.cc/ar/auth/sign-up?utm_source=docs.qcode.cc&utm_medium=tut_before&utm_campaign=knowledge_base&src=docs-ide-coze-before) أولًا، واختر الخطة المناسبة من [صفحة الأسعار](https://qcode.cc/ar/pricing?utm_source=docs.qcode.cc&utm_medium=tut_before&utm_campaign=knowledge_base&src=docs-ide-coze-before)، ثم أنشئ المفتاح في [لوحة التحكم](https://qcode.cc/ar/dashboard)
- أن تحدّد النموذج الذي تريد استدعاءه: إن أردت `claude-opus-5-5` فاتبع **المسار A (إضافة HTTP / سير العمل)**؛ وإن كنت تستخدم `gpt-6.2-sol` أو النماذج الصينية فالحساب الشخصي يتبع **المسار A**، ومدير النسخة المؤسسية الرائدة يمكنه اتباع **المسار B (نموذج مخصص أصلي)**
- أن تكون شبكتك الحالية قادرة على الوصول إلى `www.coze.cn` و`code.coze.cn` و`api.qcode.cc` و`probe.qcode.cc`


**تحتاج مفتاح API؟**

إن لم يكن لديك حساب QCode بعد، [أنشئ حساب QCode](https://qcode.cc/ar/auth/sign-up?utm_source=docs.qcode.cc&utm_medium=tut_key_step&utm_campaign=knowledge_base&src=docs-ide-coze-key) أولًا. وإذا أردت الدفع حسب الاستخدام، فاشترِ أولًا [باقة الدفع حسب الاستخدام](https://qcode.cc/ar/pay-as-you-go?utm_source=docs.qcode.cc&utm_medium=tut_key_step&utm_campaign=knowledge_base&src=docs-ide-coze-key)، ثم أنشئ مفتاح API كاملًا يبدأ بـ `cr_` من [لوحة التحكم](https://qcode.cc/ar/dashboard) وانسخه. ويمكنك الدفع ببطاقة الائتمان / الخصم (Visa / Mastercard)، أو Apple Pay / Google Pay، أو العملات المشفرة — راجع [طرق الدفع](/docs/reference/payment-methods).


## التحضير: تأكد من المدخل واختر مسار الربط

يمكن إتمام كل إعدادات Coze مباشرة في المتصفح، دون تثبيت عميل سطح مكتب مخصّص. وإن كنت معتادًا على نسخة سطح المكتب، فلا يمكنك إلا أن تمرّر المؤشر على الصفحة الرئيسية في [موقع Coze الرسمي](https://www.coze.cn) إلى «下载桌面端» (تنزيل نسخة سطح المكتب) لتنزيل حزمة التثبيت لنظام Windows أو macOS (فـ Coze ليس برنامج سطح مكتب مفتوح المصدر، ولا توجد له حزم تثبيت على GitHub Releases أو winget أو متجر Microsoft؛ وبعد التثبيت تفتح افتراضيًا على مساحة عمل وكيل Coze، لكن ضبط النموذج المخصص للمؤسسة يحتاج إلى فتح المتصفح والوصول إلى `code.coze.cn`).

بحسب نسخة حسابك والنموذج المستهدف، اختر المسار المناسب أدناه:

**المسار A: الحسابات الشخصية / حسابات الفرق (إضافة مخصصة / طلب HTTP)**

- **الجمهور المناسب**: كل حسابات Coze (بما في ذلك الحسابات الشخصية العادية، ومساحات عمل الفرق، ومستخدمو المؤسسات الذين يحتاجون إلى استدعاء `claude-opus-5-5`).
- **النماذج المدعومة**: يدعم في الوقت نفسه `claude-opus-5-5` (عبر نقطة نهاية Anthropic `https://api.qcode.cc/api/v1/messages`) و`gpt-6.2-sol` والنماذج الصينية (عبر نقطة النهاية المتوافقة مع OpenAI `https://api.qcode.cc/openai/v1/chat/completions`).
- **خطوات العمل**: أنجز أدناه **الخطوة 1 ← الخطوة 2 ← الخطوة 3 ← الخطوة 4 ← الخطوة 7** (وتجاوز الخطوتين 5 و6 المخصّصتين لمدير المؤسسة فقط).


**المسار B: مدير النسخة المؤسسية الرائدة (نموذج مخصص أصلي)**

- **الجمهور المناسب**: من فُعّلت له **النسخة المؤسسية الرائدة** في Coze وكان حسابه الحالي **مشرفًا أعلى للمؤسسة أو مشرفًا**.
- **النماذج المدعومة**: يدعم `gpt-6.2-sol` والنماذج الصينية (عبر `https://api.qcode.cc/openai/v1`)؛ و**لا يدعم سلسلة Claude** (فالمدخل الأصلي في Coze لا يوفّر بروتوكول Anthropic).
- **الميزة الأساسية**: بعد الربط وتفويض مساحات العمل يستطيع الأعضاء التبديل إليه من محدّد النماذج في صفحة تنسيق الوكيل كما لو كان نموذجًا مدمجًا، وهو يدعم الاستجابة المتدفقة أصلًا.
- **خطوات العمل**: أنجز أدناه **الخطوة 1 ← الخطوة 5 ← الخطوة 6 ← الخطوة 7** (دون إعداد إضافة HTTP في الخطوات 2–4).


## دليل الإعداد خطوة بخطوة



### تحقّق أولًا محليًا من اتصال مفتاح QCode ونقطة النهاية

قبل الدخول إلى خلفية Coze، أرسل طلب اختبار أصغر ما يمكن من طرفية محلية (Windows PowerShell أو طرفية macOS أو Linux Shell) للتأكد من أن مفتاح `cr_` والنموذج المستهدف يعملان بشكل سليم. وهكذا إن ظهر خطأ لاحقًا داخل Coze تستطيع فورًا تحديد أن المشكلة في إعدادات نموذج Coze لا في المفتاح نفسه.

بدّل إلى التبويب المطابق لعائلة النموذج الذي تنوي استدعاءه، واستبدل `cr_xxxxxxxx` بمفتاحك الحقيقي ثم نفّذ:

**التحقق من Claude (claude-opus-5-5)**

```bash
curl -sS https://api.qcode.cc/api/v1/messages \
  -H "Content-Type: application/json" \
  -H "x-api-key: cr_xxxxxxxx" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "claude-opus-5-5",
    "max_tokens": 256,
    "messages": [
      {"role": "user", "content": "مرحبًا، عرّف عن نفسك بجملة واحدة"}
    ]
  }'
```


**التحقق من GPT (gpt-6.2-sol)**

```bash
curl -sS https://api.qcode.cc/openai/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer cr_xxxxxxxx" \
  -d '{
    "model": "gpt-6.2-sol",
    "stream": false,
    "messages": [
      {"role": "user", "content": "مرحبًا، عرّف عن نفسك بجملة واحدة"}
    ]
  }'
```



إذا فعلتها بشكل صحيح فسترى: تعيد الطرفية كائن JSON كاملًا؛ ويحتوي الحقل `content[0].text` في استجابة Claude، أو الحقل `choices[0].message.content` في استجابة GPT، على تعريف بالنفس، دون كائن `error`.


**تعثّرت؟ يعيد الاختبار المحلي 401 أو model_not_available_on_endpoint**

راجع ثلاث نقاط بالترتيب: 1) يجب أن يبدأ المفتاح بـ `cr_` كاملًا، وألّا تلصق أسطرًا جديدة أو مسافات زائدة بعد علامات الاقتباس والنقطتين؛ 2) `claude-opus-5-5` يجب أن يُطلب من `https://api.qcode.cc/api/v1/messages` مع ترويسة `x-api-key`، ولا يُرسل إلى `/openai/v1`؛ 3) `gpt-6.2-sol` يجب أن يُطلب من `https://api.qcode.cc/openai/v1/chat/completions` مع `Authorization: Bearer cr_xxxxxxxx`. وفي Windows PowerShell، إن واجهت مشكلة في تهريب علامات الاقتباس المفردة، فاستخدم `curl.exe` أو تحقّق مباشرة عبر ميزة الاختبار في عقدة HTTP داخل سير عمل Coze.




### المسار A: املأ واجهة QCode في عقدة HTTP بسير العمل أو في إضافة مخصصة

سجّل الدخول إلى [موقع Coze الرئيسي](https://www.coze.cn) وادخل إلى مساحة العمل المستهدفة، ثم اختر أحد الأمرين بحسب طريقة استخدامك:

- **عقدة طلب HTTP في سير العمل (الأسرع بدءًا)**: أنشئ سير عمل جديدًا أو افتح سير عمل قائمًا، وأضف إلى اللوحة عقدة «HTTP 请求» (طلب HTTP)، واضبط طريقة الطلب على `POST`.
- **إضافة مخصصة (أسهل لإعادة الاستخدام في عدة وكلاء)**: ادخل إلى صفحة الإضافات / مكتبة الموارد في مساحة العمل، واختر إنشاء إضافة مخصصة بناءً على خدمة HTTP قائمة، ثم أضف أداة بطريقة `POST`.

وبحسب عائلة النموذج التي تريد استدعاءها، املأ عنوان URL والترويسات (Headers) وجسم طلب JSON (Body) وفق التبويب المقابل أدناه. و`{{user_prompt}}` هنا يعني المتغيّر النصي الذي تعرّفه في عقدة إدخال سير العمل أو في مدخلات الإضافة؛ وفي الإعداد الفعلي أدرجه عبر محدّد المتغيرات الذي توفّره واجهة Coze:

**Claude (بروتوكول Anthropic · claude-opus-5-5)**

| البند | ما تملؤه |
|---|---|
| طريقة الطلب | `POST` |
| عنوان URL الكامل | `https://api.qcode.cc/api/v1/messages` (وإن كانت الإضافة تفصل عنوان URL الأساسي عن المسار: املأ العنوان الأساسي بـ `https://api.qcode.cc/api` والمسار بـ `/v1/messages`) |
| الترويسة 1 | `Content-Type`: `application/json` |
| الترويسة 2 | `x-api-key`: `cr_xxxxxxxx` (استبدله بمفتاحك، **دون** إضافة البادئة `Bearer `) |
| الترويسة 3 | `anthropic-version`: `2023-06-01` |

اختر نوع Body هو `JSON`، واملأ:

```json
{
  "model": "claude-opus-5-5",
  "max_tokens": 2048,
  "messages": [
    {
      "role": "user",
      "content": "{{user_prompt}}"
    }
  ]
}
```


**GPT / النماذج الصينية (متوافق مع OpenAI · gpt-6.2-sol)**

| البند | ما تملؤه |
|---|---|
| طريقة الطلب | `POST` |
| عنوان URL الكامل | `https://api.qcode.cc/openai/v1/chat/completions` (وإن كانت الإضافة تفصل عنوان URL الأساسي عن المسار: املأ العنوان الأساسي بـ `https://api.qcode.cc/openai/v1` والمسار بـ `/chat/completions`) |
| الترويسة 1 | `Content-Type`: `application/json` |
| الترويسة 2 | `Authorization`: `Bearer cr_xxxxxxxx` (اترك مسافة إنجليزية واحدة بين `Bearer` والمفتاح) |

اختر نوع Body هو `JSON`، واملأ:

```json
{
  "model": "gpt-6.2-sol",
  "stream": false,
  "messages": [
    {
      "role": "user",
      "content": "{{user_prompt}}"
    }
  ]
}
```

وإذا أردت استخدام نموذج صيني بدلًا منه، فغيّر `"model"` فقط إلى معرّف نموذج يدعمه المسار المتوافق مع OpenAI مثل `glm-5.3` أو `kimi-k3` أو `deepseek-v4-pro` أو `qwen3.8-max`.



إذا فعلتها بشكل صحيح فسترى: طريقة الطلب هي `POST`، وعنوان URL يطابق بروتوكول عائلة النموذج بدقة، والترويسات تحتوي على المفتاح وترويسة الإصدار كاملة، ومحرّر JSON بلا أي خط أحمر نحوي.


**تعثّرت؟ يظهر خطأ في صيغة JSON، أو لا تعرف كيف تُدخل سجل المحادثة متعدد الأدوار**

تأكد أولًا من أن كل علامات الاقتباس هي علامات اقتباس مزدوجة إنجليزية `"`، وأنه لا توجد فاصلة زائدة بعد الحقل الأخير، وأن `"stream"` باقٍ على `false` (فعقدة HTTP في سير العمل والإضافات تحلّل الاستجابة افتراضيًا كـ JSON واحد، وتشغيل التدفق يجعل جسم الاستجابة أسطر `data:` متعددة يتعذّر تحليلها). وإذا كان إدخال المستخدم قد يحتوي على علامات اقتباس مزدوجة أو أسطر جديدة، فالأفضل تمريره عبر «ربط معاملات JSON / مدخلات منظّمة» في سير عمل Coze أو الإضافة، ولا تُلصق نصًا طويلًا غير مهرَّب داخل سلسلة JSON مباشرة.




### المسار A: اضبط استخراج حقول الاستجابة وجرّب التشغيل

بعد نجاح طلب HTTP عليك استخراج نصّ المحتوى من JSON العائد لتقرأه عقدة الإخراج في سير العمل أو الوكيل. ومسار الاستجابة يختلف بحسب البروتوكول، فاملأ ربط معاملات الإخراج وفق الواجهة التي أعددتها:

**استخراج استجابة Claude (صيغة Anthropic)**

بنية استجابة نموذجية:

```json
{
  "id": "msg_01...",
  "type": "message",
  "role": "assistant",
  "model": "claude-opus-5-5",
  "content": [
    {
      "type": "text",
      "text": "مرحبًا، أنا Claude، ويمكنني مساعدتك في الاستدلال والكتابة ومهام البرمجة."
    }
  ],
  "usage": {
    "input_tokens": 18,
    "output_tokens": 32
  }
}
```

- **مسار استخراج النص**: `content[0].text` (ويمكنك في سير العمل قراءة `body.content[0].text` مباشرة عبر «عقدة الشيفرة» أو إعداد معاملات الإخراج).


**استخراج استجابة GPT / النماذج الصينية (صيغة متوافقة مع OpenAI)**

بنية استجابة نموذجية:

```json
{
  "id": "chatcmpl-...",
  "object": "chat.completion",
  "model": "gpt-6.2-sol",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "مرحبًا، يمكنني مساعدتك في الأسئلة والتحليل وكتابة الشيفرة."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 18,
    "completion_tokens": 24,
    "total_tokens": 42
  }
}
```

- **مسار استخراج النص**: `choices[0].message.content` (بقراءة `body.choices[0].message.content` تحصل على الإجابة النصية الصافية).


بعد ضبط معاملات الإخراج، انقر «试运行 / 调试» (تشغيل تجريبي / تنقيح) في سير العمل أو في أداة الإضافة، ومرّر إلى `user_prompt` جملة مثل «مرحبًا، عرّف عن نفسك بجملة واحدة»، وراقب رمز حالة الاستجابة والنص المستخرج.


إذا فعلتها بشكل صحيح فسترى: يعيد التنقيح رمز حالة HTTP `200`، وتُستخرج في لوحة الإخراج إجابة نصية صافية دون بنية JSON الخارجية.


**تعثّرت؟ تنتهي مهلة التشغيل التجريبي أو يكون الحقل المستخرج فارغًا**

1) إذا انتهت مهلة الطلب، فقلّل `max_tokens` قليلًا أولًا (مثل `1024`) لاختبار رد قصير، وغيّر نطاق URL من `api.qcode.cc` إلى نقطة آسيا `asia.qcode.cc` (مثل `https://asia.qcode.cc/api/v1/messages` أو `https://asia.qcode.cc/openai/v1/chat/completions`)؛ 2) وإذا كان رمز الحالة `200` لكن الحقل المستخرج فارغ، فافتح جسم الاستجابة الأصلي `body` وتحقّق مما إذا كنت قد عكست `content[0].text` مع `choices[0].message.content`، أو نسيت تحليل سلسلة جسم الاستجابة إلى كائن JSON أولًا.




### المسار A: انشر الإضافة أو سير العمل واربطه بوكيل Coze

بعد نجاح التنقيح، انشر إضافتك المخصصة أو سير عملك إلى مساحة العمل الحالية، ثم افتح صفحة تنسيق الوكيل المستهدف:

1. في منطقة «المهارات» بصفحة التنسيق، أضف الإضافة أو سير العمل الذي نشرته للتو إلى الوكيل.
2. في «الشخصية ومنطق الرد (الموجّه النظامي)» اكتب قاعدة التفعيل بوضوح، حتى لا يتجاوز النموذج الافتراضي في Coze الإضافة ويجيب بنفسه. مثال:

```text
عندما يطلب المستخدم كتابة شيفرة معقّدة أو تحليلًا عميقًا، أو يطلب صراحةً إجابة من نموذج QCode، يجب استدعاء إضافة / سير عمل QCode المرتبط، وتمرير سؤال المستخدم كاملًا في معامل `user_prompt`، وعرض النتيجة النصية التي تعيدها الأداة كما هي للمستخدم، دون اختلاق إجابة بديلة.
```

بعد الحفظ، أرسل في نافذة «المعاينة والتنقيح» على اليمين رسالة تحقّق الشرط أعلاه (مثل «استدعِ أداة QCode وعرّف عن نفسك بجملة واحدة»)، وراقب هل استُدعيت الإضافة أو سير العمل فعليًا أثناء التنقيح.


إذا فعلتها بشكل صحيح فسترى: يظهر في مسار الاستدعاء بمنطقة المعاينة سجل تنفيذ الإضافة أو سير العمل الذي ربطته للتو، وحالته ناجحة، وفقاعة المحادثة تعرض ردًّا عائدًا من QCode.


**تعثّرت؟ لم يستدعِ الوكيل الإضافة وأجاب بنفسه مباشرة**

راجع ثلاثة مواضع بالأولوية: 1) يجب أن تكون الإضافة أو سير العمل قد نُشر فعليًا بالنقر على «نشر»، فحفظ المسودة وحده لا يجعل الاستدعاء مستقرًّا؛ 2) يجب أن يوضّح وصف الأداة (بالإنجليزية أو الصينية) ووصف معامل `user_prompt` غرضهما بدقة ليتعرّف عليه نموذج التوجيه؛ 3) وإذا كنت تريد **أن تمرّ كل رسالة مستخدم عبر QCode إلزاميًا دون أن يقرّر النموذج الافتراضي التفعيل**، فبدّل الوكيل إلى وضع التشغيل بسير العمل، ليذهب إدخال المستخدم مباشرة إلى سير عمل يحتوي عقدة HTTP لـ QCode.




### المسار B (مدير النسخة المؤسسية الرائدة فقط): اربط نموذجًا مخصصًا أصليًا من خلفية Coze Code

> هذه الخطوة والخطوة 6 **مخصّصتان فقط للمشرف الأعلى أو المشرف في النسخة المؤسسية الرائدة من Coze**. وإذا كان حسابك شخصيًا عاديًا فانتقل مباشرة إلى الخطوة 7 للتحقق من سجل الطلبات.

1. افتح Coze Code في المتصفح [code.coze.cn](https://code.coze.cn) وسجّل الدخول بحساب مدير المؤسسة.
2. انقر صورة المستخدم أسفل يسار الصفحة، واختر **حساب المؤسسة** الذي تنتمي إليه، ثم انقر أيقونة «الإعدادات» في تلك المؤسسة، وادخل إلى «إدارة المؤسسة».
3. في «إدارة المؤسسة» ادخل بالتتابع إلى **«ربط النماذج ← نموذج مخصص»**، وانقر **«ربط نموذج»**.
4. في النافذة المنبثقة املأ المعاملات وفق الجدول أدناه، وبعد الانتهاء حدّد قدرات النموذج المطلوبة (مثل استدعاء الأدوات والتفكير العميق) وطول السياق ثم احفظ:

| حقل النموذج | ما تملؤه | الشرح |
|---|---|---|
| اسم عرض النموذج | `QCode GPT 6.2 Sol` (قابل للتغيير) | يؤثر فقط على الاسم الذي يراه الأعضاء في الواجهة |
| المعرّف الفريد للنموذج | `gpt-6.2-sol` | يُكتب مباشرة في حقل `model` في الطلب؛ ويمكن كتابة معرّف نموذج صيني مثل `glm-5.3`، و**لا تكتب نموذج Claude أبدًا** |
| عنوان API للنموذج | `https://api.qcode.cc/openai/v1` | يضيف Coze `/chat/completions` تلقائيًا، فلا تكتبها يدويًا مرة أخرى |
| بروتوكول API | `OpenAI Chat/completions` | خيار ثابت في المنصة لا يمكن تغييره |
| طريقة المصادقة | `Authorization` | وبديلها طريقة `Header` (انظر التلميح المطوي أدناه) |
| مفتاح المصادقة | `cr_xxxxxxxx` | املأ مفتاح QCode؛ ويكفي التخزين بنص صريح دون الحاجة إلى Volcano KMS |


إذا فعلتها بشكل صحيح فسترى: بعد نجاح الحفظ تعود إلى قائمة «نموذج مخصص»، ويظهر فيها `QCode GPT 6.2 Sol` الذي ربطته للتو بشكل طبيعي، دون تنبيه توقف أو خلل.


**تعثّرت؟ لا تجد «ربط النماذج»، أو يعيد اختبار الاتصال 401 / 404**

- **لا ترى «ربط النماذج» إطلاقًا**: تأكد من أنك اخترت حساب المؤسسة لا الحساب الشخصي، وأن المؤسسة فُعّلت لها **النسخة المؤسسية الرائدة**، وأن دورك مشرف أعلى للمؤسسة أو مشرف. وعند عدم تحقّق الشروط لا يظهر هذا المدخل، فاتبع المسار A بدلًا منه.
- **ظهور <code>404</code>**: تحقّق من أن «عنوان API للنموذج» مكتوب إلى `/openai/v1` فقط، دون إضافة `/chat/completions` أو شرطة مائلة زائدة في النهاية.
- **ظهور <code>401</code> / فشل المصادقة**: تأكد أولًا من أن المفتاح يبدأ بـ `cr_` وبلا مسافات زائدة؛ وإذا اخترت `Authorization` وما زال الخطأ `401`، فجرّب طريقة مصادقة `Header`، واكتب في Header Key القيمة `Authorization` وفي Header Value القيمة `Bearer cr_xxxxxxxx` ثم احفظ وأعد الاختبار.




### المسار B (مدير النسخة المؤسسية الرائدة فقط): فوّض مساحات العمل المتاحة واختر النموذج في الوكيل

بعد ربط Coze للنموذج المخصص يكون **غير متاح لجميع مساحات العمل افتراضيًا**، ويجب أن يفتح المدير التفويض يدويًا ليتمكّن الأعضاء من رؤيته:

1. ابقَ في قائمة «إدارة المؤسسة ← ربط النماذج ← نموذج مخصص»، وابحث عن النموذج الذي ربطته للتو، وانقر على يمين صفّه **«… ← تعديل المساحات المتاحة»**.
2. في النافذة المنبثقة شغّل مفتاح مساحة العمل المستهدفة واحفظ.
3. عد إلى صفحة تنسيق وكيل Coze (أو اطلب من عضو في مساحة العمل المستهدفة فتح صفحة التنسيق)، وافتح محدّد النماذج، واختر `QCode GPT 6.2 Sol` الذي ربطته للتو من مجموعة **«نموذج مخصص»**.
4. اكتب في نافذة المحادثة على اليمين «مرحبًا، عرّف عن نفسك بجملة واحدة» وأرسل، وراقب هل تُطبع الاستجابة المتدفقة حرفًا بحرف بشكل طبيعي.


إذا فعلتها بشكل صحيح فسترى: مفتاح الإتاحة لمساحة العمل المستهدفة مفتوح؛ ويمكن اختيار النموذج من مجموعة «نموذج مخصص» في قائمة نماذج الوكيل، وبعد إرسال الرسالة تأتي استجابة متدفقة طبيعية دون أخطاء `401` أو `404` أو `model not found`.


**تعثّرت؟ لا يرى الأعضاء النموذج، أو تظل الرسالة تدور بلا رد**

- **الأعضاء لا يرون النموذج**: ارجع إلى «تعديل المساحات المتاحة» وتأكد من أنك اخترت مساحة العمل التي يوجد فيها العضو حاليًا، واطلب من العضو تحديث صفحة التنسيق.
- **ظهور أن النموذج غير موجود**: تحقّق مما إذا كان «المعرّف الفريد للنموذج» قد امتلأ خطأً باسم العرض (مثل كتابة `QCode GPT 6.2 Sol`)؛ فيجب أن يكون معرّف نموذج يدعمه QCode فعليًا (مثل `gpt-6.2-sol`).
- **الرسالة تدور بلا توقف**: يطلب النموذج المخصص الأصلي في Coze من المزوّد دائمًا بوضع التدفق (`stream=true`)؛ تأكد من أن عنوان URL مكتوب `https://api.qcode.cc/openai/v1` (ويمكن في بيئة البر الرئيسي استخدام `https://asia.qcode.cc/openai/v1`) وأنه غير محجوب بسياسة الخروج الشبكي للمؤسسة.




### تحقّق من سجل الطلبات على probe.qcode.cc

سواء اتبعت المسار A أو المسار B، يُستحسن في النهاية التحقق مرة واحدة من سجل البوابة الحقيقي، للتأكد من أن الرد يأتي فعلًا من QCode لا من نموذج مدمج في Coze يجيب نيابةً عنه:

1. افتح [probe.qcode.cc](https://probe.qcode.cc/) في المتصفح.
2. الصق مفتاح `cr_` نفسه الذي استخدمته في Coze، وانقر «查询» (استعلام).
3. مرّر لأسفل إلى قائمة الطلبات، وتحقّق من أن وقت أحدث سجل يطابق لحظة التنقيح أو المحادثة في Coze، وأن عمود رمز الحالة يعرض `200`.


إذا فعلتها بشكل صحيح فسترى: يظهر أعلى قائمة الطلبات سجل يطابق لحظة الاختبار، وحالته `200`، مع بيانات زمن أول حرف والزمن الكلي المقابلة.




## التحقق من النجاح

راجع البنود التالية، فإذا تطابقت جميعها فهذا يعني أن Coze موصول بـ QCode بشكل مستقر:

- أوامر الاختبار المحلي تعيد `200` ونصًّا صالحًا لكل من `claude-opus-5-5` أو `gpt-6.2-sol`؛
- **المسار A**: التشغيل التجريبي لعقدة HTTP في سير عمل Coze أو للإضافة المخصصة يعيد `200`، ويُستخرج بنجاح `content[0].text` (Claude) أو `choices[0].message.content` (GPT / النماذج الصينية)، ويظهر في منطقة معاينة الوكيل نجاح استدعاء الأداة؛
- **المسار B**: حالة «نموذج مخصص» في النسخة المؤسسية الرائدة طبيعية، ومفتاح مساحة العمل المستهدفة مفتوح، ويستطيع العضو بعد اختيار `gpt-6.2-sol` من مجموعة «نموذج مخصص» في الوكيل استلام استجابة متدفقة؛
- تجد في [probe.qcode.cc](https://probe.qcode.cc/) بالمفتاح نفسه سجل طلب بالوقت المقابل ورمز الحالة `200`.


### انتهى كل شيء

ربطت QCode بـ Coze، وأصبحت تعرف بدقة حدود المسارين: الإضافة المخصصة / طلب HTTP، والنموذج المخصص الأصلي للمؤسسة. ويمكنك بعد ذلك:

- [نقاط الوصول وصيغ API](/docs/getting-started/endpoints-and-api-paths)
- [ربط النماذج الصينية](/docs/usage/cn-models)
- [شرح الفوترة](/docs/reference/billing)
- [استكشاف الأخطاء وإصلاحها](/docs/reference/troubleshooting)
- التالي: قارن الخطط في [صفحة الأسعار](https://qcode.cc/ar/pricing?utm_source=docs.qcode.cc&utm_medium=tut_done&utm_campaign=knowledge_base&src=docs-ide-coze-done)
- ارجع إلى [لوحة التحكم](https://qcode.cc/ar/dashboard) لمراجعة الاستخدام والرصيد


## الأخطاء الشائعة

| نص الخطأ / الظاهرة | السبب | ما العمل |
|---|---|---|
| لا يوجد مدخل «ربط النماذج ← نموذج مخصص» | النموذج المخصص الأصلي متاح فقط للمشرف الأعلى أو المشرف في النسخة المؤسسية الرائدة، ولا توجد هذه القائمة للحسابات الشخصية العادية | تأكد من أنك بدّلت إلى حساب المؤسسة وأن النسخة المؤسسية الرائدة مفعّلة؛ أما الحساب الشخصي أو حساب الفريق العادي فيتبع **المسار A (إضافة مخصصة / طلب HTTP في سير العمل)** من هذا الدليل مباشرة |
| `model_not_available_on_endpoint` | كتابة `claude-opus-5-5` في نقطة النهاية المتوافقة مع OpenAI (`/openai/v1`) أو في النموذج المخصص الأصلي في Coze | نقطة النهاية المتوافقة مع OpenAI في QCode لا تقبل Claude. فاستدعاء `claude-opus-5-5` يجب أن يتم بطلب HTTP مباشر إلى نقطة نهاية Anthropic `https://api.qcode.cc/api/v1/messages`؛ والنموذج المخصص الأصلي في Coze يقبل `gpt-6.2-sol` أو النماذج الصينية فقط |
| `404 Not Found` | عدم تطابق كتابة مسار URL: كتابة `/chat/completions` زائدة في النموذج المخصص الأصلي، أو إغفال لاحقة المسار في إضافة HTTP | «عنوان API للنموذج» في النموذج المخصص الأصلي يُملأ إلى `https://api.qcode.cc/openai/v1` فقط (ويضيف Coze `/chat/completions` تلقائيًا)؛ أما عقدة طلب HTTP فتحتاج العنوان الكامل (`/api/v1/messages` أو `/openai/v1/chat/completions`) |
| `401 Unauthorized` / فشل المصادقة | المفتاح غير كامل، أو يحتوي مسافات قبله أو بعده، أو صيغة ترويسة المصادقة لا تطابق بروتوكول الواجهة | تأكد من أن المفتاح كامل ويبدأ بـ `cr_`؛ واجهة Anthropic تستخدم `x-api-key: cr_...` + `anthropic-version: 2023-06-01`؛ وواجهة HTTP المتوافقة مع OpenAI تستخدم `Authorization: Bearer cr_...`؛ وإن ظلّ النموذج المخصص الأصلي يعيد 401 مع `Authorization`، فجرّب مصادقة `Header` واكتب `Bearer cr_...` يدويًا |
| `Model not found` / النموذج غير موجود | كتابة اسم العرض المخصص في معرّف النموذج، أو خطأ إملائي في اسم النموذج | راجع «المعرّف الفريد للنموذج» أو حقل `"model"` في JSON، واكتب معرّف نموذج يدعمه QCode فعليًا (مثل `claude-opus-5-5` و`gpt-6.2-sol` و`glm-5.3`) |
| فشل تحليل JSON في عقدة HTTP أو دوران المحادثة الأصلية بلا توقف | إعداد التدفق معاكس للحالة: عقدة HTTP تتلقى تدفق SSE فلا يمكن تحليله كـ JSON عادي، أو مسار المؤسسة الأصلي محجوب شبكيًا | يجب كتابة `"stream": false` صراحةً في جسم طلب إضافة HTTP / سير العمل؛ والنموذج المخصص الأصلي للمؤسسة يستخدم `stream=true` دائمًا، فتأكد من استقرار الاتصال بـ `api.qcode.cc` أو جرّب `asia.qcode.cc` |
| الأعضاء لا يرون النموذج المخصص الذي رُبط للتو في قائمة نماذج الوكيل | النموذج المرتبط حديثًا في خلفية المؤسسة يكون مغلقًا لجميع مساحات العمل افتراضيًا | يعود المدير إلى قائمة «نموذج مخصص»، وينقر على يمين النموذج «… ← تعديل المساحات المتاحة»، ويشغّل مفتاح مساحة العمل المستهدفة يدويًا |

## الأسئلة الشائعة

### ماذا أفعل بعد انتهاء صلاحية المفتاح؟

الأمر يختلف بحسب الحالتين:

- مفتاح **الخطة الشخصية** لا يمكن تجديده بعد انتهاء الصلاحية، بل يجب فتح خطة جديدة والحصول على مفتاح جديد؛
- مفتاح **باقة الدفع حسب الاستخدام** يعود للعمل تلقائيًا بعد شراء باقة جديدة، دون تعديل أي إعداد في Coze.

وإذا غيّرت المفتاح، فحدّث بالتزامن مفتاح الترويسة في إضافة Coze المخصصة / عقدة HTTP في سير العمل (المسار A)، أو عدّل مفتاح المصادقة للنموذج المقابل في «Coze Code ← إدارة المؤسسة ← ربط النماذج ← نموذج مخصص» (المسار B).

### لماذا لا يستطيع الحساب الشخصي العادي استبدال النموذج الافتراضي لوكيل Coze مباشرة؟

هذا قيد في صلاحيات منصة Coze وتصميم منتجها: فمدخل «نموذج مخصص» الأصلي متاح حاليًا للمشرف الأعلى والمشرف في المؤسسة ذات النسخة الرائدة فقط، ولا توجد في خلفية الحساب الشخصي أي خانة لضبط عنوان Base URL للنموذج المخصص. وإن أراد الحساب الشخصي استخدام QCode في Coze، فيمكنه ربط QCode كأداة أو عقدة معالجة عبر إضافة مخصصة أو عقدة طلب HTTP في سير العمل.

### لماذا لا يمكن ربط `claude-opus-5-5` في «نموذج مخصص» بالنسخة المؤسسية الرائدة؟

بروتوكول API لـ «نموذج مخصص» الأصلي في Coze ثابت على OpenAI Chat/completions، ولا توفّر المنصة خيار بروتوكول Anthropic Messages؛ في حين أن نقطة النهاية المتوافقة مع OpenAI في QCode تخدم GPT والنماذج الصينية فقط، ولا تقبل طلبات Claude. ولذلك فإن مستخدم المؤسسة إذا أراد استدعاء `claude-opus-5-5` في Coze فعليه أيضًا الاتصال المباشر بـ `https://api.qcode.cc/api/v1/messages` عبر إضافة مخصصة أو عقدة طلب HTTP في سير العمل.

### ماذا أفعل إذا انتهت مهلة طلب HTTP في سير العمل أحيانًا؟

راجع ثلاثة جوانب: 1) بدّل نطاق الطلب من النقطة العالمية `api.qcode.cc` إلى نقطة آسيا `asia.qcode.cc` (المسار أقرب، والمفتاح نفسه يعمل)؛ 2) اضبط `max_tokens` بشكل معقول في جسم الطلب (مثل `1024`–`2048`) واختصر الموجّه لتقليل زمن التوليد الواحد؛ 3) زد إعداد المهلة في عقدة HTTP بسير العمل قليلًا حتى لا يُقطع الرد الطويل مبكرًا بسبب عقدة Coze.

### هل يحتاج Coze إلى تنزيل نسخة سطح المكتب؟ وهل توجد حزمة تثبيت مفتوحة المصدر؟

لا. فسواء أعددت إضافة مخصصة، أو بنيت سير عمل، أو أدرت النماذج المخصصة للمؤسسة في `code.coze.cn`، يمكنك إتمام كل ذلك في واجهة الويب في المتصفح. وبالفعل يوفّر Coze نسخة سطح مكتب لنظامي Windows وmacOS، لكنه ليس برنامجًا مفتوح المصدر، ولا توجد حزم تثبيت على GitHub Releases أو winget أو متجر Microsoft، بل تُحصل عليها فقط من «下载桌面端» (تنزيل نسخة سطح المكتب) في موقع [www.coze.cn](https://www.coze.cn) الرسمي.

## نظرة سريعة على الربط والنماذج المتاحة

### عقد QCode وعناوين البروتوكول

النقاط الثلاث متطابقة في قدرات الخدمة، والمفتاح `cr_` نفسه يعمل عليها جميعًا، فاختر ما يناسب بيئة شبكة Coze لديك:

| العقدة | واجهة Anthropic (المسار A فقط لطلبات HTTP) | عنوان Base URL المتوافق مع OpenAI (المسار A يضيف `/chat/completions`؛ والمسار B يُملأ إلى هنا) |
|---|---|---|
| العالمية | `https://api.qcode.cc/api/v1/messages` | `https://api.qcode.cc/openai/v1` |
| آسيا (المفضّلة في البر الرئيسي) | `https://asia.qcode.cc/api/v1/messages` | `https://asia.qcode.cc/openai/v1` |
| أمريكا الشمالية / أوروبا | `https://us.qcode.cc/api/v1/messages` | `https://us.qcode.cc/openai/v1` |

### النماذج الموصى بها ومقابلتها لمسارات Coze

| النموذج | معرّف النموذج | المسار المناسب | نقطة نهاية البروتوكول |
|---|---|---|---|
| Claude Opus 5.5 | `claude-opus-5-5` | المسار A فقط (إضافة مخصصة / HTTP في سير العمل) | Anthropic (`/api/v1/messages`) |
| GPT 6.2 Sol | `gpt-6.2-sol` | المسار A والمسار B (النموذج المخصص الأصلي للمؤسسة) كلاهما | متوافق مع OpenAI (`/openai/v1`) |
| النماذج الصينية الأساسية | `glm-5.3` و`kimi-k3` و`deepseek-v4-pro` و`qwen3.8-max` وغيرها | المسار A والمسار B كلاهما | متوافق مع OpenAI (`/openai/v1`) |

> لا يوفّر QCode حاليًا نماذج Gemini، فاختر في Coze نموذجًا من Claude أو GPT أو النماذج الصينية. ومعرّفات النماذج الصينية الكاملة في [ربط النماذج الصينية](/docs/usage/cn-models)، والطرازات المعروضة للبيع حاليًا وفق [qcode.cc/models](https://qcode.cc/ar/models).

## الوثائق ذات الصلة

- [نقاط الوصول وصيغ API](/docs/getting-started/endpoints-and-api-paths) — جدول المصدر الحقيقي للبروتوكول × عائلة النموذج
- [ربط النماذج الصينية](/docs/usage/cn-models) — قائمة النماذج الصينية المتاحة على نقطة النهاية المتوافقة مع OpenAI
- [شرح الفوترة](/docs/reference/billing) — قواعد فوترة الخطط وباقات الدفع حسب الاستخدام
- [استكشاف الأخطاء وإصلاحها](/docs/reference/troubleshooting) — رموز الحالة العامة وفحص الاتصال الشبكي
- [وثائق Coze الرسمية لربط النموذج المخصص](https://docs.coze.cn/guides/deploy_custom_model) — الشرح الرسمي للربط الأصلي في النسخة المؤسسية الرائدة