# تكامل OpenClaw

> **آخر تحقق**: 2026-09-18 · 📄 وفق الوثائق الرسمية (OpenClaw v2026.9.4، صدر في 2026-09-11)

## نظرة سريعة

| البند | التفاصيل |
|---|---|
| النماذج التي يمكنك استخدامها | Claude ✅ (بروتوكول Anthropic) · GPT ✅ · نماذج صينية ✅ · Gemini ❌ (لا يوفر QCode نماذج Gemini حاليًا) |
| البروتوكول وBase URL | Anthropic: `https://api.qcode.cc/api` · OpenAI: `https://api.qcode.cc/openai/v1` |
| مكان الإعداد | `~/.openclaw/openclaw.json` (JSON5، يُعاد تحميله فوريًا) أو معالج `openclaw onboard` |
| الوثائق الرسمية | [المزوّدون المخصصون](https://github.com/openclaw/openclaw/blob/main/docs/concepts/model-providers/custom-providers.md) · [docs.openclaw.ai](https://docs.openclaw.ai) |

OpenClaw هو **مساعد ذكاء اصطناعي مفتوح المصدر يعمل على أجهزتك الخاصة**: تتصل عملية Gateway مستضافة ذاتيًا بـ Discord وTelegram وSlack وiMessage وغيرها من قنوات الدردشة، مع تطبيقات أصلية لـ macOS / Windows / Linux. **إنه ليس محرر شيفرة** — يوجد في هذا القسم لأنه يُستخدم كثيرًا كـ«بوابة مساعد شخصي عبر نماذج متعددة»، ولأنه يدعم أصلًا أي نقطة نهاية متوافقة مع OpenAI / Anthropic.

## المتطلبات المسبقة

- OpenClaw مثبّت (المثبّت الرسمي `curl -fsSL https://openclaw.ai/install.sh | bash`؛ يتطلب التثبيت المباشر عبر npm إصدار Node 24.16+، والتوصية الرسمية هي 26+، راجع [README](https://github.com/openclaw/openclaw#readme)).
- مفتاح `cr_` من QCode.cc (أنشئ واحدًا في [لوحة التحكم](https://qcode.cc/dashboard)). **لا** حاجة إلى حساب منفصل لدى مزوّد نموذج.
- لا يتطلب OpenClaw نفسه أي حساب خاص به؛ فكل نموذج يأتي من المزوّدين الذين تضبطهم.

## الإعداد

### المسار أ: تحرير ملف الإعدادات مباشرةً (موصى به)

أضف كتلة `models.providers` إلى `~/.openclaw/openclaw.json`. الملف بصيغة JSON5 (تُسمح التعليقات والفواصل اللاحقة) ويعيد Gateway تحميله فوريًا — دون حاجة إلى إعادة التشغيل:

```json5
{
  models: {
    mode: "merge", // keep built-in providers, append QCode
    providers: {
      qcode: {
        baseUrl: "https://api.qcode.cc/api",
        apiKey: "${QCODE_API_KEY}",
        api: "anthropic-messages",
        models: [
          { id: "claude-sonnet-5", name: "Claude Sonnet 5", input: ["text", "image"] },
        ],
      },
      qcode_openai: {
        baseUrl: "https://api.qcode.cc/openai/v1",
        apiKey: "${QCODE_API_KEY}",
        api: "openai-completions",
        models: [
          { id: "gpt-5.6", name: "GPT-5.6" },
          { id: "glm-5.3", name: "GLM-5.3" },
        ],
      },
    },
  },
}
```

ثلاث ملاحظات (جميعها من [وثائق المزوّدين المخصصين](https://github.com/openclaw/openclaw/blob/main/docs/concepts/model-providers/custom-providers.md) الرسمية):

- يدعم `apiKey` الاستبدال بـ `${ENV_VAR}`؛ وتوصي وثائق OpenClaw بمراجع الأسرار / متغيرات البيئة بدلًا من مفتاح حرفي.
- `api` هو محول الطلبات: بروتوكول Anthropic هو `anthropic-messages`، وبروتوكول OpenAI هو `openai-completions`. تعيين `baseUrl` فقط دون `api` يؤدي افتراضيًا إلى `openai-completions`.
- لا يتلقى النموذج الصور (الرؤية) إلا إذا عيّنت `input: ["text", "image"]` صراحةً؛ وإلا فتُمرَّر الصور كمراجع نصية.

### المسار ب: إدخال «مزوّد مخصص» في معالج onboard

```bash
openclaw onboard --install-daemon
```

اختر **مزوّدًا مخصصًا** في قائمة المزوّدين (ضمن **المزيد…** عندما لا يظهر مباشرةً)، ثم أدخل Base URL ومفتاح API والتوافق ومعرّف النموذج. يتحقق المعالج من إكمال حقيقي قبل الحفظ (الصيغة الرسمية: *يتحقق من رد حقيقي قبل الحفظ*)، ما يكشف الأخطاء المطبعية في URL فورًا.

المكافئ غير التفاعلي، لنموذج Claude:

```bash
openclaw onboard --non-interactive --accept-risk \
  --auth-choice custom-api-key \
  --custom-base-url "https://api.qcode.cc/api" \
  --custom-model-id "claude-sonnet-5" \
  --custom-api-key "$QCODE_API_KEY" \
  --custom-compatibility anthropic
```

🔴 تختلف كتابتان: خيار المعالج `--custom-compatibility` يقبل `anthropic`، بينما يقبل `api` في ملف الإعدادات `anthropic-messages` (راجع [وثائق onboard](https://github.com/openclaw/openclaw/blob/main/docs/cli/onboard.md)).
## تحقق من أنه يعمل

1. إذا استخدمت المسار B، فقد أجرى معالج الإعداد بالفعل فحصًا مباشرًا لك (طلب حقيقي واحد قبل الحفظ).
2. بعد المسار A، اطلب من الوكيل شيئًا بسيطًا مثل `ping`. إذا فشل، فتحقق أولًا من صياغة JSON5 في `~/.openclaw/openclaw.json` — فالتعليقات والفواصل الشاردة تفسد الملف.
3. للتحقق فقط من وجود المسار ووصول المفتاح:

```bash
curl -s -o /dev/null -w '%{http_code}\n' -X POST https://api.qcode.cc/api/v1/messages \
  -H "x-api-key: $QCODE_API_KEY"
# → 401 = key invalid; any code other than a JSON error = path reachable
```

4. يُسجَّل كل طلب (بما في ذلك طلبات OpenClaw) في [probe.qcode.cc](https://probe.qcode.cc) — أدخل مفتاحك لترى النموذج وحالة الطلبات الفعلية. هل ما زال يفشل؟ اتبع قائمة التحقق في [استكشاف الأخطاء وإصلاحها](/docs/reference/troubleshooting).

## القيود المعروفة

- **تحذير بشأن صيغة Base URL**: يستخدم كلا المثالين الرسميين لـ `anthropic-messages` (Synthetic، MiniMax) قيمة `baseUrl` **بدون `/v1`** (مثل `https://api.minimax.io/anthropic`)، لذا تستخدم هذه الصفحة `https://api.qcode.cc/api`. المسار الدقيق الذي يُلحقه OpenClaw غير موثق حرفيًا ولم يُختبَر مباشرةً هنا. إذا أعادت الطلبات 404، فغيّر `baseUrl` إلى المسار الكامل `https://api.qcode.cc/api/v1/messages`.
- محوّل `openai-responses` موثق للأنظمة الخلفية التي تدعم `/v1/responses` فقط. على QCode، تخدم نقطة نهاية Responses نماذج GPT؛ وجّه النماذج الصينية عبر `openai-completions` (مصفوفة البروتوكولات: [نقاط النهاية ومسارات API](/docs/getting-started/endpoints-and-api-paths)).
- على نقاط نهاية `anthropic-messages` غير المباشرة، يكتم OpenClaw ترويسات beta الخاصة بـ Anthropic قبل إرسال الطلب (سلوك موثق) — وهو مفيد للبوابات التابعة لجهات خارجية. إذا واجهت أداة أخرى أخطاء 400 الخاصة بـ `anthropic-beta`، فليست هذه مشكلة في OpenClaw.
- يوجد محوّل Gemini (`google-generative-ai`) في التعداد الرسمي، لكن QCode لا يوفر نماذج Gemini حاليًا، لذا لا يُقدَّم مثال.
- توجد الوثائق الرسمية على فرع `main` في GitHub؛ وقد يتأخر docs.openclaw.ai قليلًا عنها.

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

- [نقاط النهاية ومسارات API](/docs/getting-started/endpoints-and-api-paths) — البروتوكولات وكيفية تعبئة Base URL
- [نظرة عامة على توافق الأدوات](/docs/ide/tool-compatibility) — دعم البروتوكولات عبر جميع الأدوات
- [إعداد CC Switch](/docs/ide/cc-switch) — تبديل المزوّد عبر واجهة رسومية لـ Claude Code / Codex
- [النماذج الصينية](/docs/usage/cn-models) — معرّفات GLM / Kimi / DeepSeek / Qwen المتاحة للبيع حاليًا
- [استكشاف الأخطاء وإصلاحها](/docs/reference/troubleshooting)
- [إعداد LobsterAI](/docs/ide/lobsterai) — عميل سطح المكتب من NetEase Youdao المبني على OpenClaw؛ تقبل نماذجه المخصصة عناوين Anthropic Compatible وOpenAI Compatible
- [إعداد AutoClaw](/docs/ide/autoclaw) — تطبيق OpenClaw المحلي من Zhipu؛ تستخدم نماذجه المخصصة بروتوكول OpenAI Chat