# إعداد Crush

> **آخر تحقق**: 2026-09-18 · 📄 وفق الوثائق الرسمية (Crush v0.95.0، صدر في 2026-09-16)

## نظرة سريعة

| العنصر | التفاصيل |
|---|---|
| النماذج التي يمكنك استخدامها | Claude ✅ (`type: anthropic`) · GPT ✅ · النماذج الصينية ✅ (`openai-compat`) · Gemini ❌ (لا يوجد مسار Gemini موثّق هنا) |
| البروتوكول وBase URL | Anthropic: `https://api.qcode.cc/api` · OpenAI: `https://api.qcode.cc/openai/v1` |
| مكان الإعداد | على مستوى المشروع `crush.json` / على مستوى المستخدم `~/.config/crush/crush.json` |
| الوثائق الرسمية | [charmbracelet/crush](https://github.com/charmbracelet/crush)

[Crush](https://github.com/charmbracelet/crush) هو وكيل البرمجة بالذكاء الاصطناعي الذي يركّز على الطرفية من Charm (مكتوب بـGo). يدعم **المزوّدين المخصصين**، لذا يمكن إعداد QCode.cc بصفته مزوّدًا.

> **ملاحظة حول التسمية**: كان المستودع في الأصل `charmbracelet/opencode` وأصبح الآن `crush` (يعيد URL القديم التوجيه 301؛ ولم يذكر المشرفون السبب قط). إنه **مشروع مختلف** عن [OpenCode](/docs/ide/opencode) (opencode.ai) — ولاحظ أن Crush يوفّر أيضًا مزوّد نموذج مدمجًا يُسمى `opencode`، وهو أمر آخر من جهة Charm، لا ينبغي الخلط بينهما.

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

تقبل المزوّدات المخصصة في Crush القيمتين `anthropic` و`openai-compat` بصفتهما `type`. **بالنسبة إلى Claude، استخدم `anthropic`** — لا تقبل نقطة نهاية OpenAI من QCode نماذج Claude (انظر [نقاط النهاية ومسارات API](/docs/getting-started/endpoints-and-api-paths)).

| النموذج الذي تريده | `type` | `base_url` |
|---|---|---|
| Claude | `anthropic` | `https://api.qcode.cc/api` |
| GPT / العائلات الصينية الأربع | `openai-compat` | `https://api.qcode.cc/openai/v1` |

## التثبيت

```bash
# Homebrew
brew install charmbracelet/tap/crush

# or download a prebuilt binary from Releases
# https://github.com/charmbracelet/crush/releases
```

تحقّق (**اعتمد على المخرجات الفعلية، لا على رقم إصدار في أي وثيقة**):

```bash
crush --version
```

## الإعداد

أنشئ `crush.json` في جذر المشروع، أو على مستوى المستخدم في `~/.config/crush/crush.json` (= `$XDG_CONFIG_HOME/crush/crush.json`؛ لاحظ أن `~/.local/share/crush/` يحتوي على ملفات حالة تقول الوثائق الرسمية إنه لا يجب تعديلها). تعتمد الإصدارات الأحدث أيضًا صيغة `crushrc` (Bash DSL)؛ ولا يزال إعداد JSON يُقرأ:

```json
{
  "$schema": "https://charm.land/crush.json",
  "providers": {
    "qcode": {
      "type": "anthropic",
      "base_url": "https://api.qcode.cc/api",
      "api_key": "$QCODE_KEY",
      "extra_headers": { "anthropic-version": "2023-06-01" },
      "models": [
        {
          "id": "claude-sonnet-5",
          "name": "QCode Sonnet 5",
          "cost_per_1m_in": 2,
          "cost_per_1m_out": 10,
          "context_window": 1000000,
          "default_max_tokens": 8192,
          "cost_per_1m_in_cached": 0.2,
          "cost_per_1m_out_cached": 2.5,
          "can_reason": true,
          "supports_attachments": true
        },
        {
          "id": "claude-haiku-5-5",
          "name": "QCode Haiku 5.5",
          "cost_per_1m_in": 0.1,
          "cost_per_1m_out": 0.5,
          "context_window": 1000000, "default_max_tokens": 4096,
          "cost_per_1m_in_cached": 0.01,
          "cost_per_1m_out_cached": 0.125,
          "can_reason": true,
          "supports_attachments": true
        }
      ]
    }
  }
}
```

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

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

| الحقل | المعنى |
|-------|---------|
| `type` | يحدد `anthropic` بروتوكول Messages الأصلي |
| `base_url` | توقّف عند `/api` — **يضيف Crush `/v1/messages` بنفسه** |
| `api_key` | يدعم توسيع متغيرات البيئة `$VAR` |
| `extra_headers` | يحتاج بروتوكول Anthropic إلى `anthropic-version` |
| `models[]` | يتيح لك سرد النماذج تجاوز معاملات التكلفة / السياق؛ وإذا أغفلته، يكتشف Crush النماذج تلقائيًا عبر `<base>/v1/models` (`discover_models` مفعّل افتراضيًا). يجب أن يطابق كل `id` [qcode.cc/models](https://qcode.cc/models) حرفًا بحرف |

> **من البر الرئيسي للصين**، استبدل المضيف بـ`https://asia.qcode.cc/api` (عقدة آسيا، الأقرب من كوريا / تايوان / هونغ كونغ)؛ ولا يتغير المفتاح.
> لا تؤثر `cost_per_1m_*` (بما في ذلك مفتاحا `*_cached` اللذان يتطلبهما المخطط الرسمي) إلا في عرض تقدير الاستخدام الخاص بـCrush، وليس في الفوترة الفعلية — تتبع الأرقام النموذجية نسبة تخزين مؤقت نموذجية؛ عدّلها وفق معدلات التخزين المؤقت الحقيقية على [qcode.cc/models](https://qcode.cc/models).
## التحقق

```bash
crush run "reply with exactly: OK"
```

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

**لإثبات أن حركة المرور تذهب فعلاً إلى QCode**، وجّه `base_url` عن قصد إلى مسار غير موجود ثم شغّل الأمر مجدداً. ينبغي أن ترى خطأ 404 صريحاً يعرض كامل URL:

```text
404 Not Found {"error":"Not Found","message":"Route /api/xxx/v1/messages not found"}
```

يثبت هذا الخطأ أن Crush يركّب `base_url + /v1/messages` وأن إعداداتك أصبحت سارية. (هذا ضبط سلبي: مجرد النجاح لا يثبت أن مزوّدك هو المستخدَم — فقد يكون Crush انتقل احتياطياً إلى مزوّد آخر.)

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

```bash
# interactive
crush

# non-interactive
crush run "make this function async"

# pipes
cat README.md | crush run "make this clearer" > README.new.md

# specific directory with debug logging
crush --debug --cwd /path/to/project

# auto-accept every permission (use with care)
crush --yolo
```

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

### `model_not_available_on_endpoint`

`type` هو `openai-compat` بينما النموذج من Claude. بدّل إلى `type: "anthropic"` مع `base_url` = `https://api.qcode.cc/api`.

### 401 مفتاح API غير صالح

لم يُحقن متغير البيئة، أو يحتوي المفتاح على فراغات زائدة. تحقق من أن `echo $QCODE_KEY` يبدأ بـ `cr_`.

### لا يظهر النموذج في قائمة الاختيار

لا يعرض Crush إلا النماذج المدرجة صراحةً في `models[]`. أضف مدخلة وأعد التشغيل.

## ذات صلة

- [نقاط النهاية ومسارات API](/docs/getting-started/endpoints-and-api-paths) — جدول البروتوكول × عائلة النموذج
- [تكامل OpenCode](/docs/ide/opencode) — وكيل طرفية مختلف (وليس المشروع نفسه)
- [النماذج الصينية](/docs/usage/cn-models) — GLM / Kimi / DeepSeek / Qwen
- [إعداد مزوّد Goose](/docs/ide/goose) — وكيل طرفية آخر؛ تدخل العناوين في `ANTHROPIC_HOST` / `OPENAI_HOST` عبر `goose configure`