# تكامل CodeWhale (سابقًا DeepSeek-TUI)

> **آخر تحقق**: 2026-10-26 · 📄 وفق الوثائق الرسمية (CodeWhale v0.10.2، صدر في 2026-10-24 (سابقًا DeepSeek-TUI)؛ فحص 2026-09-18 الإصدار v0.9.13 الذي صدر في 2026-09-14)

## نظرة سريعة

| العنصر | التفاصيل |
|---|---|
| النماذج التي يمكنك استخدامها | Claude ✅ (المزوّد anthropic، ويضيف `/v1/messages` بنفسه) · GPT ✅ · النماذج الصينية ✅ (المزوّد openai) · Gemini ❌ (لا يوفّر QCode نماذج Gemini في الوقت الحالي) |
| البروتوكول وBase URL | Anthropic: `https://api.qcode.cc/api` · OpenAI: `https://api.qcode.cc/openai/v1` |
| مكان الإعداد | `~/.codewhale/config.toml` (المسار القديم `~/.deepseek/` احتياطي فقط عندما يكون المجلد الجديد غائبًا) |
| الوثائق الرسمية | [codewhale-hq/Codewhale](https://github.com/codewhale-hq/Codewhale) |

> **⚠️ تمت إعادة تسمية المشروع.** أصبح `DeepSeek-TUI` الآن **CodeWhale**. تغيّر الملف التنفيذي من
> `deepseek` إلى `codewhale`، وانتقل ملف الإعدادات من `~/.deepseek/config.toml` إلى
> `~/.codewhale/config.toml`. الرجوع الاحتياطي مشروط: عقد الترحيل الرسمي هو
> **القراءة مع الرجوع الاحتياطي، والكتابة إلى الجديد** — تقرأ العمليات من `~/.codewhale/` أولًا وترجع إلى
> `~/.deepseek/` **فقط عندما يكون ذلك هو المجلد الوحيد الموجود**، بينما تذهب كل كتابة إلى المجلد
> الجديد. كذلك، منذ **v0.9.0** حُذف الأمران `deepseek` و`deepseek-tui`؛ ونقاط
> الدخول هي `codewhale` و`codew` (اسم مستعار للتسهيل) و`codewhale-tui`. الموقع القديم
> `deepseek-tui.com` يعيد التوجيه الآن بـ301 إلى [codewhale.net](https://codewhale.net).
> لم يتغيّر URL هذه الصفحة.

[CodeWhale](https://codewhale.net) هو وكيل برمجة بالذكاء الاصطناعي يعمل في الطرفية، وله عشرات من
المزوّدين من الدرجة الأولى (`anthropic`، `openai`، `deepseek`، `ollama`، `vllm`، `openrouter` وغيرها؛ تشير الوثائق
إلى `ProviderKind::ALL` في المصدر باعتباره القائمة الفعلية، وهي تزيد وتنقص بين الإصدارات — شغّل
`/provider` لرؤية المجموعة في نسختك المبنية). يدعم كلًّا من **بروتوكول Anthropic Messages
الأصلي** و**بروتوكول OpenAI Chat Completions**، ويمكن توجيه أيٍّ منهما إلى QCode.cc.
## 🔴 اقرأ هذا أولًا: يتطلب Claude المزوّد anthropic

نقطة النهاية لدى QCode المتوافقة مع OpenAI **لا تقبل نماذج Claude** — وضع `claude-…` في `[providers.openai]` يعيد `model_not_available_on_endpoint`. انظر جدول التوافق في [نقاط النهاية ومسارات API](/docs/getting-started/endpoints-and-api-paths).

| النموذج الذي تريده | مزوّد CodeWhale الذي يجب استخدامه | QCode `base_url` |
|---|---|---|
| Claude (`claude-opus-5` / `claude-sonnet-5` …) | `anthropic` | `https://api.qcode.cc/api` |
| GPT (`gpt-6-sol` …) | `openai` | `https://api.qcode.cc/openai/v1` |
| GLM / Kimi / DeepSeek / Qwen | أي منهما | انظر الصفين أعلاه |

## لماذا تستخدم CodeWhale مع QCode

- **واجهة TUI مألوفة**: أوضاع Plan / Work / Operate، مع أنماط الصلاحيات Ask / Auto-Review / Full Access (`Shift+Tab`) وMCP / Shell / Git / الوكلاء الفرعيين المدمجة
- **مفتاح API واحد**: يتقاسم حصة خطتك في QCode مع Claude Code وCodex CLI
- **تبديل المزوّد**: التنقل بين anthropic / openai / ollama / vllm داخل الأداة نفسها
- **يعمل جيدًا من البر الرئيسي الصيني**: `asia.qcode.cc` (عقدة آسيا، قريبة من كوريا / تايوان / هونغ كونغ) هي أقرب نقطة نهاية
- **مفتوح المصدر بالكامل**: مرخّص بموجب MIT، وملف الإعدادات قابل للتدقيق

## 1. التثبيت

الخيار الرسمي الأول هو سكربت التثبيت من GitHub Releases؛ وتسمّي الوثائق npm وCargo مسارَي تغليف **ثانويين**:

```bash
# Officially recommended (macOS / Linux): installs the release binary
curl -fsSL https://codewhale.net/install.sh | sh

# npm - the official docs call this a secondary packaging route (Node 18+)
npm install -g codewhale

# Homebrew - full name taps and trusts in one step (the two-step form fails on Homebrew 7.x)
brew install Hmbown/deepseek-tui/codewhale

# Cargo - source build; the crate is codewhale-cli, the command it installs is codewhale
cargo install codewhale-cli --locked
```

حدود المنصات وتفاصيلها: [وثائق التثبيت الرسمية](https://codewhale.net/en/install).

> **تغيّر في 2026-10-26:** تقول صفحة التثبيت الرسمية الآن إن الصيغة المكوّنة من خطوتين (`brew tap Hmbown/deepseek-tui` ثم `brew install codewhale`) تفشل على Homebrew 7.x؛ استخدم الاسم الكامل أعلاه، أو شغّل `brew trust hmbown/deepseek-tui` أولًا. كان إصدار هذه الصفحة بتاريخ 2026-09-18 يعرض الصيغة المكوّنة من خطوتين.

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

```bash
codewhale --version
```
## 2. إعداد Claude (المزوّد anthropic)

حرّر `~/.codewhale/config.toml`:

```toml
# ~/.codewhale/config.toml

provider = "anthropic"

[providers.anthropic]
api_key  = "cr_your_qcode_key"
base_url = "https://api.qcode.cc/api"
model    = "claude-sonnet-5"
```

| الحقل | المعنى |
|------|---------|
| `provider` | يُضبط على `"anthropic"` في المستوى الأعلى ليكون البروتوكول الافتراضي هو Messages الأصلي |
| `api_key` | من لوحة تحكم QCode.cc، ويبدأ بـ `cr_`. يرسله CodeWhale ضمن `x-api-key` |
| `base_url` | توقّف عند `/api`؛ يضيف CodeWhale المسار `/v1/messages` (بحسب الوثائق الرسمية). لا تُضِف `/` في النهاية، ولا تكتب `/v1/messages` بنفسك |
| `model` | معرّف نموذج Claude يبيعه QCode — راجع [qcode.cc/models](https://qcode.cc/models). تتعامل الوثائق مع `[providers.<table>].model` على أنه **تجاوز على مستوى المزوّد**؛ أما النموذج الافتراضي فمكانه `default_text_model` في المستوى الأعلى |

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

تعمل متغيرات البيئة بدلًا من ملف الإعدادات؛ وتفضّل الوثائق الآن المجموعة العامة `CODEWHALE_*`:

```bash
export CODEWHALE_PROVIDER="anthropic"
export CODEWHALE_BASE_URL="https://api.qcode.cc/api"
export CODEWHALE_MODEL="claude-sonnet-5"
export ANTHROPIC_API_KEY="cr_your_qcode_key"

codewhale
```

لا تزال متغيرات المزوّد الخاصة (`ANTHROPIC_BASE_URL` / `ANTHROPIC_MODEL`) مقبولة، وكذلك الخيار `codewhale --provider anthropic`.

### تغييرات في v0.10.1–v0.10.2 تؤثر في هذا الإعداد (2026-10-26)

لم يتغيّر اسم الملف التنفيذي (`codewhale`) ولا مسار الإعدادات (`~/.codewhale/config.toml`) في وثائق التثبيت والإعدادات الرسمية التي جرى التحقق منها في 2026-10-26. تغييران مرتبطان بالإعدادات منذ v0.10.0:

- **v0.10.1** — أصبح للمستوى الأعلى معنى واحد: «إن `base_url` أو `api_key` في المستوى الأعلى ضمن `config.toml` يعنيان الآن الشيء نفسه في كل مكان.» تظل الملفات القديمة تعمل: «تُقرأ المفاتيح على أنها `[providers.deepseek]` (أو المزوّد الذي يحدّدانه عبر مضيفه الرسمي)، وعند الحفظ التالي تُنقل إلى هناك مع نسخة احتياطية لمرة واحدة وملاحظة من سطر واحد»، ويعرض `codewhale config doctor` ما هو قيد الاستخدام (ملاحظات الإصدار). تكتب هذه الصفحة القيمتين داخل `[providers.anthropic]` / `[providers.openai]`، لذا فهي غير متأثرة.
- **v0.10.2 (2026-10-24)** — يمكن لأمر التثبيت الرسمي تثبيت الإصدار: `curl -fsSL https://codewhale.net/install.sh | CODEWHALE_VERSION="v0.10.2" sh` (ملاحظات الإصدار). ولا يزال الأمر غير المثبّت `curl -fsSL https://codewhale.net/install.sh | sh` من صفحة التثبيت موجودًا.
## 3. إعداد GPT والنماذج الصينية (مزوّد openai)

يمكن تعايش عدة مزوّدين ضمن إعداد واحد؛ للتبديل استخدم `codewhale --provider <id>`:

```toml
[providers.openai]
api_key  = "cr_your_qcode_key"
base_url = "https://api.qcode.cc/openai/v1"
model    = "gpt-6-sol"
```

اجعل `base_url` ينتهي عند `/openai/v1`؛ يضيف CodeWhale `/chat/completions`. إذا تطلّب أحد إصدارات البناء لاحقة مختلفة، فالمفتاح الرسمي المخصص لذلك هو `path_suffix` داخل `[providers.openai]` — لا تُقحمه في `base_url`.

تعمل العائلات الصينية الأربع (`glm-5.2` / `kimi-k3` / `deepseek-v4-pro` / `qwen3.8-max` …) على **كلا** نقطتي النهاية، لذا يصلح أي من المزوّدين. المعرّفات مدرجة في
[النماذج الصينية](/docs/usage/cn-models).

## 4. النماذج المتاحة

| معرّف النموذج | المزوّد | الأنسب لـ |
|---------|----------|----------|
| `claude-opus-5` | `anthropic` | تخطيط مكثّف / بنية معقدة |
| `claude-sonnet-5` | `anthropic` | البرمجة اليومية (**موصى به**) |
| `claude-haiku-5-5` | `anthropic` | مهام صغيرة سريعة / تكلفة منخفضة |
| `gpt-6-sol` | `openai` | الطراز الرائد من OpenAI |
| `glm-5.2` / `kimi-k3` / `deepseek-v4-pro` / `qwen3.8-max` | أي منهما | خيارات صينية أقل تكلفة |

> لا تزال نماذج 4.x مثل `claude-sonnet-4-6` و`claude-opus-4-8` تُباع. القائمة الكاملة
> والأسعار المباشرة على [qcode.cc/models](https://qcode.cc/models).

اعرض ما يمكنك استدعاؤه الآن — لاحظ أن نقطتي النهاية تُرجعان قائمتين **مختلفتين**:

```bash
# Claude and Chinese models (Anthropic endpoint)
curl https://api.qcode.cc/v1/models -H "Authorization: Bearer cr_your_qcode_key"

# GPT (OpenAI endpoint)
curl https://api.qcode.cc/openai/v1/models -H "Authorization: Bearer cr_your_qcode_key"
```

## 5. التحقق من الاتصال

```bash
KEY="cr_your_qcode_key"

# Claude (Anthropic protocol) — should return JSON containing content
curl -X POST 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-sonnet-5","max_tokens":32,"messages":[{"role":"user","content":"ping"}]}'

# GPT (OpenAI protocol) — should return JSON containing choices
curl -X POST https://api.qcode.cc/openai/v1/chat/completions \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-6-sol","max_tokens":32,"messages":[{"role":"user","content":"ping"}]}'
```

ثم شغّل:

```bash
codewhale
```

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

| العَرَض | السبب | الحل |
|---------|-------|-----|
| `model_not_available_on_endpoint` | وُضع نموذج Claude في `[providers.openai]` | استخدم `[providers.anthropic]` مع `base_url` = `https://api.qcode.cc/api` |
| `Invalid API key` | مفتاح خاطئ، أو مسافات بيضاء غير مقصودة | تحقق من أنه يبدأ بـ `cr_` ولا توجد مسافات في بدايته أو نهايته |
| 404 | شرطة مائلة زائدة في `base_url`، أو بادئة مسار خاطئة | قارن مع [نقاط النهاية ومسارات API](/docs/getting-started/endpoints-and-api-paths) |
| تعديلات الإعداد لا يكون لها أثر | لا يعود العقد الرسمي إلى الدليل القديم إلا عندما يكون هو الوحيد الموجود، لذا نادرًا ما يكون ملف `~/.deepseek/config.toml` القديم هو السبب؛ والأكثر شيوعًا بكثير هو أولوية بيانات الاعتماد (الإعداد المحفوظ / حلقة المفاتيح يتغلبان على متغيرات البيئة) أو ملف `.codewhale/config.toml` على مستوى المشروع يُطبق فوق الملف العام | شغّل الأمر الرسمي `codewhale auth status` (يطبع المصدر الذي يفوز) و`/config audit`؛ تغيير Base URL للمزوّد يتطلب إعادة تشغيل عميل النموذج |

## مواضيع ذات صلة

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