# إعداد Droid (Factory)

> **آخر تحقق**: 2026-09-18 · 📄 وفق الوثائق الرسمية (Droid CLI v0.222.0 صدر في 2026-09-18؛ الإصدارات متكررة — اعتمد على `droid --version`)

## نظرة سريعة

| البند | التفاصيل |
|---|---|
| النماذج التي يمكنك استخدامها | Claude ✅ (`provider: "anthropic"`) · GPT ✅ · النماذج الصينية ✅ (`provider: "generic-chat-completion-api"`) · Gemini ❌ (لا يوجد مزوّد بهذا الاسم في Droid) |
| البروتوكول وBase URL | Anthropic: `https://api.qcode.cc/api` · OpenAI Chat: `https://api.qcode.cc/openai/v1` |
| مكان الإعداد | `~/.factory/settings.json` (يُنشأ تلقائيًا عند أول تشغيل لـ `droid`) |
| الوثائق الرسمية | [BYOK](https://docs.factory.ai/model-independence/byok) · [الإعدادات](https://docs.factory.ai/droid-cli/settings)

[Droid](https://docs.factory.ai/droid-cli/overview) هو وكيل البرمجة بالذكاء الاصطناعي الطرفي من Factory. يدعم **النماذج المخصصة BYOK**، لذا يمكن إضافة QCode.cc كنموذج مخصص.

## أي بروتوكول

يختار Droid البروتوكول عبر حقل `provider`. **مع Claude استخدم `anthropic`** — نقطة نهاية OpenAI لدى QCode لا تقبل نماذج Claude (راجع [نقاط النهاية ومسارات API](/docs/getting-started/endpoints-and-api-paths)).

| النموذج المطلوب | `provider` | `baseUrl` |
|---|---|---|
| Claude | `anthropic` | `https://api.qcode.cc/api` |
| GPT / العائلات الصينية الأربع | `generic-chat-completion-api` (متوافق مع Chat-Completions) | `https://api.qcode.cc/openai/v1` |

> 🔴 لا تكتب `"provider": "openai"` — فقد خصّصتها Factory لـ **OpenAI Responses API** («استخدم provider: `"generic-chat-completion-api"` ما لم تكن تستدعي API الرسمي لـ OpenAI أو Anthropic»، [وثائق BYOK](https://docs.factory.ai/model-independence/byok)). نماذج GPT / النماذج الصينية على QCode تتحدث Chat Completions، لذا استخدم `generic-chat-completion-api`.

## التثبيت

```bash
curl -fsSL https://app.factory.ai/cli | sh
```

يثبَّت في `~/.local/bin/droid`. إذا أبلغ المثبّت أن PATH غير مهيأ، فأضف السطر الذي يطبعه إلى `~/.zshrc` / `~/.bashrc`.

تحقق (**اعتمد على الإخراج الفعلي**):

```bash
droid --version
```

## الإعداد

حرّر `~/.factory/settings.json` (**يُنشأ تلقائيًا عند أول تشغيل لـ `droid`**؛ ويعمل أيضًا ملف على مستوى المشروع `.factory/settings.local.json` — يُدمج فوقه، وتذكّر إضافته إلى gitignore):

```json
{
  "customModels": [
    {
      "model": "claude-sonnet-5",
      "displayName": "QCode Sonnet 5",
      "baseUrl": "https://api.qcode.cc/api",
      "apiKey": "${QCODE_KEY}",
      "provider": "anthropic",
      "maxOutputTokens": 8192
    },
    {
      "model": "claude-haiku-5-5",
      "displayName": "QCode Haiku 5.5",
      "baseUrl": "https://api.qcode.cc/api",
      "apiKey": "${QCODE_KEY}",
      "provider": "anthropic",
      "maxOutputTokens": 4096
    }
  ]
}
```

أدخل المفتاح عبر البيئة:

```bash
export QCODE_KEY="cr_your_qcode_key"
```

| الحقل | المعنى |
|-------|---------|
| `model` | معرّف النموذج المُرسل إلى API؛ يجب أن يطابق [qcode.cc/models](https://qcode.cc/models) تمامًا |
| `displayName` | التسمية في منتقي النماذج؛ حرة الصياغة |
| `baseUrl` | ينتهي عند `/api`؛ ويضيف Droid المسار `/v1/messages` بنفسه |
| `apiKey` | يدعم مراجع متغيرات البيئة `${VAR}` |
| `provider` | `anthropic` مع Claude |
| `maxOutputTokens` | الحد الأقصى للإخراج لكل رد |

> وفق وثائق Factory، **تبقى مفاتيح API محلية ولا تُرفع إلى خوادم Factory**.
> من البر الرئيسي للصين، استبدل المضيف بـ `https://asia.qcode.cc/api` (عقدة آسيا، الأقرب بين كوريا / تايوان / هونغ كونغ).
## التحقق

```bash
droid exec --model "claude-sonnet-5" "reply with exactly: OK"
```

تعني `OK` أنك متصل.

**التحقق السلبي** (لإثبات أن الإعدادات أصبحت سارية فعليًا): وجّه `baseUrl` مؤقتًا إلى مسار غير موجود ثم شغّل الأمر مجددًا — يجب أن يفشل. النجاح وحده لا يثبت أنه تم استخدام نقطة النهاية الخاصة بك.

## الاستخدام اليومي

```bash
# interactive
droid

# non-interactive
droid exec "run the tests and fix the failures"

# specific working directory
droid --cwd /path/to/project

# run inside a git worktree (isolated changes)
droid -w feature-x

# autonomy level
droid --auto medium
```

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

### `model_not_available_on_endpoint`

قيمة `provider` متوافقة مع OpenAI بينما النموذج من Claude. اضبط `"provider": "anthropic"` مع `baseUrl` = `https://api.qcode.cc/api`.

### 401 / فشل المصادقة

لم يتم توسيع `${QCODE_KEY}` (المتغير غير مُصدَّر)، أو يحتوي المفتاح على مسافات زائدة. تحقق من أن `echo $QCODE_KEY` يبدأ بـ `cr_`.
فخ آخر: وضع الإعدادات في `~/.factory/config.json` **القديم** (حقول snake_case) — رسميًا، الملف القديم **لا** يوسّع مراجع متغيرات البيئة في `apiKey`، لذا سيُرسَل `${QCODE_KEY}` حرفيًا بصفته المفتاح. استخدم `settings.json`.

### النموذج مفقود من منتقي النماذج

لا تظهر إلا النماذج المدرجة في `customModels[]`. أضف إدخالًا وأعد التشغيل.

## ذات صلة

- [نقاط النهاية ومسارات API](/docs/getting-started/endpoints-and-api-paths) — جدول البروتوكول × عائلة النموذج
- [إعداد Crush](/docs/ide/crush) — وكيل طرفية آخر
- [النماذج الصينية](/docs/usage/cn-models) — GLM / Kimi / DeepSeek / Qwen