# 🚀 OmniRoute — بوابة الذكاء الاصطناعي المجانية

### لا تتوقف أبدًا عن البرمجة. التوجيه الذكي إلى **نماذج الذكاء الاصطناعي المجانية ومنخفضة التكلفة** مع الرجوع التلقائي.

_وكيل API العالمي الخاص بك - نقطة نهاية واحدة، أكثر من 36 موفرًا، بدون توقف. الآن مع تنسيق الوكيل **MCP & A2A**._

**إكمالات الدردشة • التضمينات • إنشاء الصور • الفيديو • الموسيقى • الصوت • إعادة الترتيب • خادم MCP • بروتوكول A2A • 100٪ TypeScript **

---

<div align="center">

[![إصدار npm](https://img.shields.io/npm/v/omniroute?color=cb3837&logo=npm)](https://www.npmjs.com/package/omniroute)
[![Docker Hub](https://img.shields.io/docker/v/diegosouzapw/omniroute?label=Docker%20Hub&logo=docker&color=2496ED)](https://hub.docker.com/r/diegosouzapw/omniroute)
[![الترخيص](https://img.shields.io/github/license/diegosouzapw/OmniRoute)](https://github.com/diegosouzapw/OmniRoute/blob/main/LICENSE)
[![موقع الويب](https://img.shields.io/badge/Website-omniroute.online-blue?logo=google-chrome&logoColor=white)](https://omniroute.online)
[![WhatsApp](https://img.shields.io/badge/WhatsApp-Community-25D366?logo=whatsapp&logoColor=white)](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t)

[🌐 الموقع الإلكتروني](https://omniroute.online) • [🚀 البداية السريعة](#-quick-start) • [💡 الميزات](#-key-features) • [📖 المستندات](#-documentation) • [💰 التسعير](#-pricing-at-a-glance) • [💬 واتساب](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t)

</div>

🌐 **متوفر باللغة:** 🇺🇸 [الإنجليزية](../../README.md) | 🇧🇷 [البرتغالية (البرازيل)](../pt-BR/README.md) | 🇪🇸 [الإسبانية](../es/README.md) | 🇫🇷 [Français](../fr/README.md) | 🇮🇹 [الإيطالية](../it/README.md) | 🇷🇺 [Русский](../ru/README.md) | 🇨🇳 [中文 (简体)](../zh-CN/README.md) | 🇩🇪 [الألمانية](../de/README.md) | 🇮🇳 [هندي](../in/README.md) | 🇹🇭 [ไทย](../th/README.md) | 🇺🇦 [أوكرانيا](../uk-UA/README.md) | 🇸🇦 [العربية](../ar/README.md) | 🇯🇵 [日本語](../ja/README.md) | 🇻🇳 [تيانج فيت](../vi/README.md) | 🇧🇬 [بلغارسكي](../bg/README.md) | 🇩🇰 [الدانسك](../da/README.md) | 🇫🇮 [سومي](../fi/README.md) | 🇮🇱 [العربية](../he/README.md) | 🇭🇺 [المجرية](../hu/README.md) | 🇮🇩 [البهاسا الإندونيسية](../id/README.md) | 🇰🇷 [한국어](../ko/README.md) | 🇲🇾 [البهاسا ملايو](../ms/README.md) | 🇳🇱 [هولندا](../nl/README.md) | 🇳🇴 [نورسك](../no/README.md) | 🇵🇹 [البرتغالية (البرتغال)](../pt/README.md) | 🇷🇴 [روماني](../ro/README.md) | 🇵🇱 [بولسكي](../pl/README.md) | 🇸🇰 [سلوفينسينا](../sk/README.md) | 🇸🇪 [سفينسكا](../sv/README.md) | 🇵🇭 [فلبينية](../phi/README.md)

---

## 🖼️ لوحة التحكم الرئيسية

<div align="center">
  <img src="./docs/screenshots/MainOmniRoute.png" alt="OmniRoute Dashboard" width="800"/>
</div>

---

## 📸 معاينة لوحة التحكم

<details>
<summary><b>انقر لرؤية لقطات شاشة لوحة القيادة</b></summary>

| صفحة                  | لقطة شاشة                                          |
| --------------------- | -------------------------------------------------- |
| ** مقدمو الخدمة **    | ![مقدمو الخدمة](docs/screenshots/01-providers.png) |
| **المجموعات**         | ![المجموعات](docs/screenshots/02-combos.png)       |
| **تحليلات**           | ![تحليلات](docs/screenshots/03-analytics.png)      |
| **الصحة**             | ![الصحة](docs/screenshots/04-health.png)           |
| **مترجم**             | ![مترجم](docs/screenshots/05-translator.png)       |
| **الإعدادات**         | ![الإعدادات](docs/screenshots/06-settings.png)     |
| **أدوات سطر الأوامر** | ![أدوات CLI](docs/screenshots/07-cli-tools.png)    |
| **سجلات الاستخدام**   | ![الاستخدام](docs/screenshots/08-usage.png)        |
| **نقطة النهاية**      | ![نقطة النهاية](docs/screenshots/09-endpoint.png)  |

</details>

---

### 🚀 New in v2.0.9+ — Playground, CLI Fingerprints & ACP

| Feature                                    | What It Does                                                                                                                                  |
| ------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------- |
| 🎮 **Model Playground**                    | Dashboard page to test any model directly — provider/model/endpoint selectors, Monaco Editor, streaming, abort, timing                        |
| 🔏 **CLI Fingerprint Matching**            | Per-provider header/body ordering to match native CLI signatures — toggle per provider in Settings > Security. **Your proxy IP is preserved** |
| 🤝 **ACP Support (Agent Client Protocol)** | CLI agent discovery (Codex, Claude, Goose, Gemini CLI, OpenClaw), process spawner, `/api/acp/agents` endpoint                                 |
| 🤖 **ACP Agents Dashboard**                | Debug > Agents page — grid of 14 agents with install status, version, custom agent form for any CLI tool                                      |
| 🔧 **Custom Model `apiFormat` Routing**    | Custom models with `apiFormat: "responses"` now correctly route to the Responses API translator                                               |
| 🏢 **Codex Workspace Isolation**           | Multiple Codex workspaces per email — OAuth correctly separates connections by workspace ID                                                   |
| 🔄 **Electron Auto-Update**                | Desktop app checks for updates + auto-install on restart                                                                                      |

### 🤖 موفر الذكاء الاصطناعي المجاني لوكلاء البرمجة المفضلين لديك

_قم بتوصيل أي أداة IDE أو CLI مدعومة بالذكاء الاصطناعي من خلال OmniRoute - بوابة واجهة برمجة التطبيقات المجانية للترميز غير المحدود._

  <table>
    <tr>
      <td align="center" width="110">
        <a href="https://github.com/openclaw/openclaw">
          <img src="./public/providers/openclaw.png" alt="OpenClaw" width="48"/><br/>
          <b>OpenClaw</b>
        </a><br/><sub>⭐ 205K</sub>
      </td>
      <td align="center" width="110">
        <a href="https://github.com/HKUDS/nanobot">
          <img src="./public/providers/nanobot.png" alt="NanoBot" width="48"/><br/>
          <b>NanoBot</b>
        </a><br/>
        <sub>⭐ 20.9K</sub>
      </td>
      <td align="center" width="110">
        <a href="https://github.com/sipeed/picoclaw">
          <img src="./public/providers/picoclaw.jpg" alt="PicoClaw" width="48"/><br/>
          <b>PicoClaw</b>
        </a><br/>
        <sub>⭐ 14.6K</sub>
      </td>
      <td align="center" width="110">
        <a href="https://github.com/zeroclaw-labs/zeroclaw">
          <img src="./public/providers/zeroclaw.png" alt="ZeroClaw" width="48"/><br/>
          <b>زيرومخلب</b>
        </a><br/>
        <sub>⭐ 9.9K</sub>
      </td>
      <td align="center" width="110">
        <a href="https://github.com/nearai/ironclaw">
          <img src="./public/providers/ironclaw.png" alt="IronClaw" width="48"/><br/>
          <b>IronClaw</b>
        </a><br/>
        <sub>⭐ 2.1K</sub>
      </td>
    </tr>
    <tr>
      <td align="center" width="110">
        <a href="https://github.com/anomalyco/opencode">
          <img src="./public/providers/opencode.svg" alt="OpenCode" width="48"/><br/>
          <b>OpenCode</b>
        </a><br/>
        <sub>⭐ 106K</sub>
      </td>
      <td align="center" width="110">
        <a href="https://github.com/openai/codex">
          <img src="./public/providers/codex.png" alt="Codex CLI" width="48"/><br/>
          <b>Codex
        </a><br/>
        <sub>⭐ 60.8K</sub>
      </td>
      <td align="center" width="110">
        <a href="https://github.com/anthropics/claude-code">
          <img src="./public/providers/claude.png" alt="Claude Code" width="48"/><br/>
          <b>كلود كود</b>
        </a><br/>
        <sub>⭐ 67.3K</sub>
      </td>
      <td align="center" width="110">
        <a href="https://github.com/google-gemini/gemini-cli">
          <img src="./public/providers/gemini-cli.png" alt="Gemini CLI" width="48"/><br/>
          <b>الجوزاء CLI</b>
        </a><br/>
        <sub>⭐ 94.7K</sub>
      </td>
      <td align="center" width="110">
        <a href="https://github.com/Kilo-Org/kilocode">
          <img src="./public/providers/kilocode.png" alt="Kilo Code" width="48"/><br/>
          <b>كيلو كود</b>
        </a><br/>
        <sub>⭐ 15.5K</sub>
      </td>
    </tr>
  </table>

<sub>📡 يتصل جميع الوكلاء عبر <code>http://localhost:20128/v1</code> أو <code>http://cloud.omniroute.online/v1</code> - تكوين واحد ونماذج غير محدودة و حصة</sub>

---

## 🤔 لماذا OmniRoute؟

**توقف عن إهدار المال وضرب الحدود:**

- <img src="https://img.shields.io/badge/✗-e74c3c?style=flat-square" height="16"/> تنتهي حصة الاشتراك غير المستخدمة كل شهر
- حدود معدل <img src="https://img.shields.io/badge/✗-e74c3c?style=flat-square" height="16"/> تمنعك من الترميز المتوسط
- <img src="https://img.shields.io/badge/✗-e74c3c?style=flat-square" height="16"/> واجهات برمجة التطبيقات باهظة الثمن (20-50 دولارًا شهريًا لكل مزود)
- <img src="https://img.shields.io/badge/✗-e74c3c?style=flat-square" height="16"/> التبديل اليدوي بين مقدمي الخدمة

** OmniRoute يحل هذا: **

- ✅ **تعظيم الاشتراكات** - تتبع الحصة، استخدم كل جزء منها قبل إعادة التعيين
- ✅ **الرجوع التلقائي** - الاشتراك → مفتاح واجهة برمجة التطبيقات → رخيص → مجاني، بدون توقف
- ✅ **حسابات متعددة** - جولة روبن بين الحسابات لكل مزود
- ✅ **عالمي** - يعمل مع Claude Code وCodex وGemini CLI وCursor وCline وOpenClaw وأي أداة CLI

---

## 📧 الدعم> 💬 **انضم إلى مجتمعنا!** [مجموعة WhatsApp](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t) - احصل على المساعدة وشارك النصائح وابق على اطلاع.

- **الموقع الإلكتروني**: [omniroute.online](https://omniroute.online)
- **GitHub**: [github.com/diegosouzapw/OmniRoute](https://github.com/diegosouzapw/OmniRoute)
- **المشاكل**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues)
- **واتساب**: [مجموعة المجتمع](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t)
- **المساهمة**: راجع [CONTRIBUTING.md](CONTRIBUTING.md)، أو افتح علاقة عامة، أو اختر `good first issue`
- **المشروع الأصلي**: [9router by decolua](https://github.com/decolua/9router)

---

## 🔄 كيف يعمل

```
┌─────────────┐
│  Your CLI   │  (Claude Code, Codex, Gemini CLI, OpenClaw, Cursor, Cline...)
│   Tool      │
└──────┬──────┘
       │ http://localhost:20128/v1
       ↓
┌─────────────────────────────────────────┐
│           OmniRoute (Smart Router)        │
│  • Format translation (OpenAI ↔ Claude) │
│  • Quota tracking + Embeddings + Images │
│  • Auto token refresh                   │
└──────┬──────────────────────────────────┘
       │
       ├─→ [Tier 1: SUBSCRIPTION] Claude Code, Codex, Gemini CLI
       │   ↓ quota exhausted
       ├─→ [Tier 2: API KEY] DeepSeek, Groq, xAI, Mistral, NVIDIA NIM, etc.
       │   ↓ budget limit
       ├─→ [Tier 3: CHEAP] GLM ($0.6/1M), MiniMax ($0.2/1M)
       │   ↓ budget limit
       └─→ [Tier 4: FREE] iFlow, Qwen, Kiro (unlimited)

Result: Never stop coding, minimal cost
```

---

## 🎯 ما يحله OmniRoute — 30 مشكلة حقيقية وحالات استخدام

> **يواجه كل مطور يستخدم أدوات الذكاء الاصطناعي هذه المشكلات يوميًا.** تم تصميم OmniRoute لحلها جميعًا — بدءًا من تجاوز التكاليف وحتى الكتل الإقليمية، ومن تدفقات OAuth المعطلة إلى عمليات البروتوكول وإمكانية مراقبة المؤسسة.

<details>
<summary><b>💸 1. "أدفع مقابل اشتراك باهظ الثمن ولكن لا يزال يتم مقاطعتي بسبب الحدود"</b></summary>

يدفع المطورون ما بين 20 إلى 200 دولار شهريًا مقابل Claude Pro أو Codex Pro أو GitHub Copilot. حتى عند الدفع، فإن الحصة لها حد أقصى — 5 ساعات من الاستخدام، أو حدود أسبوعية، أو حدود لسعر الدقيقة. في منتصف جلسة الترميز، يتوقف الموفر عن الاستجابة ويفقد المطور التدفق والإنتاجية.

**كيف يحل OmniRoute المشكلة:**

- **الاحتياطي الذكي ذو 4 طبقات** — في حالة نفاد حصة الاشتراك، تتم إعادة التوجيه تلقائيًا إلى مفتاح واجهة برمجة التطبيقات ← رخيص ← مجاني بدون أي تدخل يدوي
- **تتبع الحصص في الوقت الفعلي** — يُظهر استهلاك الرمز المميز في الوقت الفعلي مع العد التنازلي لإعادة التعيين (5 ساعات، يوميًا، وأسبوعيًا)
- **دعم الحسابات المتعددة** — حسابات متعددة لكل مزود مع نظام روبن تلقائي — عند نفاد الحساب، يتم التبديل إلى التالي
- **مجموعات مخصصة** — سلاسل احتياطية قابلة للتخصيص مع 6 إستراتيجيات موازنة (الملء أولاً، جولة روبن، P2C، عشوائي، الأقل استخدامًا، الأمثل من حيث التكلفة)
- **حصص الدستور الغذائي** — مراقبة حصص مساحة عمل الشركة/الفريق مباشرة في لوحة المعلومات

</details>

<details>
<summary><b>🔌 2. "أحتاج إلى استخدام موفري خدمات متعددين ولكن لكل منهم واجهة برمجة تطبيقات مختلفة"</b></summary>

يستخدم OpenAI تنسيقًا واحدًا، ويستخدم Claude (Anthropic) تنسيقًا آخر، ويستخدم Gemini تنسيقًا آخر. إذا أراد أحد المطورين اختبار النماذج من موفري خدمات مختلفين أو إجراء بديل فيما بينهم، فسيحتاج إلى إعادة تكوين مجموعات تطوير البرامج (SDK)، وتغيير نقاط النهاية، والتعامل مع التنسيقات غير المتوافقة. لدى موفري الخدمة المخصصين (FriendLI، NIM) نقاط نهاية نموذجية غير قياسية.

**كيف يحل OmniRoute المشكلة:**

- **نقطة النهاية الموحدة** — تعمل نقطة `http://localhost:20128/v1` واحدة كوكيل لجميع مقدمي الخدمة الذين يزيد عددهم عن 36
- **تنسيق الترجمة** — تلقائي وشفاف: OpenAI ↔ Claude ↔ Gemini ↔ Responses API
- **تطهير الاستجابة** — إزالة الحقول غير القياسية (`x_groq`، `usage_breakdown`، `service_tier`) التي تكسر OpenAI SDK v1.83+
- **تطبيع الدور** — تحويل `developer` → `system` لمقدمي الخدمات غير التابعين لـ OpenAI؛ `system` → `user` لـ GLM/ERNIE
- **Think Tag Extraction** — يستخرج كتل `<think>` من نماذج مثل DeepSeek R1 إلى `reasoning_content` القياسية
- **الإخراج المنظم لـ Gemini** — التحويل التلقائي `json_schema` → `responseMimeType`/`responseSchema`
- **الإعدادات الافتراضية لـ `stream` هي `false`** — تتماشى مع مواصفات OpenAI، وتتجنب SSE غير المتوقع في Python/Rust/Go SDKs</details>

<details>
<summary><b>🌐 3. "مزود الذكاء الاصطناعي الخاص بي يحظر منطقتي/بلدي"</b></summary>

يقوم مقدمو الخدمة مثل OpenAI/Codex بحظر الوصول من مناطق جغرافية معينة. يحصل المستخدمون على أخطاء مثل `unsupported_country_region_territory` أثناء اتصالات OAuth وAPI. وهذا أمر محبط بشكل خاص للمطورين من البلدان النامية.

**كيف يحل OmniRoute المشكلة:**

- **تكوين الوكيل ثلاثي المستوى** — وكيل قابل للتكوين على 3 مستويات: عالمي (كل حركة المرور)، لكل مزود (موفر واحد فقط)، ولكل اتصال/مفتاح
- **شارات الوكيل المرمزة بالألوان** — المؤشرات المرئية: 🟢 الوكيل العالمي، 🟡 وكيل الموفر، 🔵 وكيل الاتصال، يظهر دائمًا عنوان IP
- **تبادل رمز OAuth عبر الوكيل** — يمر تدفق OAuth أيضًا عبر الوكيل، مما يؤدي إلى حل مشكلة `unsupported_country_region_territory`
- **اختبارات الاتصال عبر الوكيل** — تستخدم اختبارات الاتصال الوكيل الذي تم تكوينه (لا مزيد من التجاوز المباشر)
- **دعم SOCKS5** — دعم وكيل SOCKS5 الكامل للتوجيه الخارجي
- ** انتحال بصمة إصبع TLS ** — بصمة TLS تشبه المتصفح عبر `wreq-js` لتجاوز اكتشاف الروبوتات

</details>

<details>
<summary><b>🆓 4. "أريد استخدام الذكاء الاصطناعي للبرمجة ولكن ليس لدي المال"</b></summary>

لا يستطيع الجميع دفع ما بين 20 إلى 200 دولار شهريًا مقابل اشتراكات الذكاء الاصطناعي. يحتاج الطلاب والمطورون من البلدان الناشئة والهواة والمستقلون إلى الوصول إلى نماذج عالية الجودة بدون تكلفة.

**كيف يحل OmniRoute المشكلة:**

- **موفرو الطبقة المجانية المضمنون** — دعم أصلي لمقدمي الخدمات المجانيين بنسبة 100%: iFlow (8 نماذج غير محدودة)، Qwen (3 نماذج غير محدودة)، Kiro (Claude مجانًا)، Gemini CLI (180 ألف/شهر مجانًا)
- **Ollama Cloud** — Cloud-hosted Ollama models at `api.ollama.com` with free "Light usage" tier; use `ollamacloud/<model>` prefix
- **المجموعات المجانية فقط** — السلسلة `gc/gemini-3-flash → if/kimi-k2-thinking → qw/qwen3-coder-plus` = 0 USD/الشهر بدون أي توقف عن العمل
- **أرصدة NVIDIA NIM المجانية** — 1000 رصيد مجاني مدمج
- **استراتيجية التكلفة المحسنة** — استراتيجية التوجيه التي تختار تلقائيًا أرخص مزود متاح

</details>

<details>
<summary><b>🔒 5. "أحتاج إلى حماية بوابة الذكاء الاصطناعي الخاصة بي من الوصول غير المصرح به"</b></summary>

عند تعريض بوابة AI للشبكة (LAN، VPS، Docker)، يمكن لأي شخص لديه العنوان استهلاك الرموز المميزة/الحصة النسبية للمطور. بدون الحماية، تكون واجهات برمجة التطبيقات (API) عرضة لإساءة الاستخدام والحقن الفوري وإساءة الاستخدام.

**كيف يحل OmniRoute المشكلة:**

- **إدارة مفاتيح واجهة برمجة التطبيقات** — الإنشاء والتدوير وتحديد النطاق لكل مزود من خلال صفحة `/dashboard/api-manager` المخصصة
- **أذونات على مستوى النموذج** — تقييد مفاتيح واجهة برمجة التطبيقات (API) على نماذج محددة (`openai/*`، أنماط أحرف البدل)، مع تبديل السماح للكل/تقييد
- **API Endpoint Protection** — اطلب مفتاحًا لـ `/v1/models` وقم بحظر موفري خدمة محددين من القائمة
- **Auth Guard + CSRF Protection** — جميع مسارات لوحة المعلومات محمية بالبرمجيات الوسيطة `withAuth` + رموز CSRF
- **محدد المعدل** — تحديد معدل لكل IP مع نوافذ قابلة للتكوين
- **تصفية IP** — القائمة المسموح بها/القائمة المحظورة للتحكم في الوصول
- **حماية الحقن الفوري** — التعقيم ضد أنماط المطالبة الضارة
- **تشفير AES-256-GCM** — بيانات الاعتماد مشفرة في حالة عدم النشاط

</details>

<details>
<summary><b>🛑 6. "تعطل مزود الخدمة الخاص بي وفقدت تدفق الترميز الخاص بي"</b></summary>يمكن أن يصبح موفرو الذكاء الاصطناعي غير مستقرين، أو يعرضون أخطاء 5xx، أو يصلون إلى حدود المعدلات المؤقتة. إذا كان أحد المطورين يعتمد على موفر واحد، فسيتم مقاطعته. بدون قواطع الدائرة، يمكن أن تؤدي عمليات إعادة المحاولة المتكررة إلى تعطل التطبيق.

**كيف يحل OmniRoute المشكلة:**

- **قاطع الدائرة الكهربائية لكل مزود** — فتح/إغلاق تلقائي مع حدود قابلة للتكوين وفترة تهدئة (مغلق/مفتوح/نصف مفتوح)
- **التراجع الأسي** — تأخير إعادة المحاولة التدريجي
- **مكافحة الرعد القطيع** — Mutex + حماية الإشارة ضد عواصف إعادة المحاولة المتزامنة
- **السلاسل الاحتياطية المجمعة** — إذا فشل الموفر الأساسي، فسيتم دخوله تلقائيًا عبر السلسلة دون أي تدخل
- **Combo Circuit Breaker** — التعطيل التلقائي لمقدمي الخدمات الفاشلين ضمن سلسلة التحرير والسرد
  | 🎯 **Endpoint-Aware Models** | Custom models declare supported endpoints + API format |
- **لوحة معلومات الصحة** — مراقبة وقت التشغيل، وحالات قاطع الدائرة، وعمليات التأمين، وإحصائيات ذاكرة التخزين المؤقت، ووقت الاستجابة p50/p95/p99

</details>

<details>
<summary><b>🔧 7. "تكوين كل أداة من أدوات الذكاء الاصطناعي أمر ممل ومتكرر"</b></summary>

يستخدم المطورون Cursor وClaude Code وCodex CLI وOpenClaw وGemini CLI وKilo Code... تحتاج كل أداة إلى تكوين مختلف (نقطة نهاية واجهة برمجة التطبيقات، المفتاح، النموذج). تعد إعادة التكوين عند تبديل مقدمي الخدمات أو النماذج مضيعة للوقت.

**كيف يحل OmniRoute المشكلة:**

- **لوحة تحكم أدوات CLI** — صفحة مخصصة مع إعداد بنقرة واحدة لـ Claude Code، وCodex CLI، وOpenClaw، وKilo Code، وAntigravity، وCline
- **GitHub Copilot Config Generator** — يُنشئ `chatLanguageModels.json` لرمز VS مع اختيار نموذج مجمع
- **معالج الإعداد** — إعداد إرشادي من 4 خطوات للمستخدمين لأول مرة
- **نقطة نهاية واحدة، جميع الطرز** — قم بتكوين `http://localhost:20128/v1` مرة واحدة، وقم بالوصول إلى أكثر من 36 موفرًا

</details>

<details>
<summary><b>🔑 8. "إدارة رموز OAuth المميزة من موفري خدمات متعددين أمر جحيم"</b></summary>

Claude Code، وCodex، وGemini CLI، وCopilot — جميعهم يستخدمون OAuth 2.0 مع الرموز المميزة التي تنتهي صلاحيتها. يحتاج المطورون إلى إعادة المصادقة باستمرار، والتعامل مع `client_secret is missing`، و`redirect_uri_mismatch`، والفشل في الخوادم البعيدة. يعد OAuth على LAN/VPS مشكلة بشكل خاص.

**كيف يحل OmniRoute المشكلة:**

- **التحديث التلقائي للرمز المميز** — يتم تحديث رموز OAuth المميزة في الخلفية قبل انتهاء الصلاحية
- **OAuth 2.0 (PKCE) مدمج** — التدفق التلقائي لـ Claude Code وCodex وGemini CLI وCopilot وKiro وQwen وiFlow
- **OAuth متعدد الحسابات** — حسابات متعددة لكل مزود عبر استخراج الرمز المميز JWT/ID
- **OAuth LAN/Remote Fix** — اكتشاف IP الخاص لـ `redirect_uri` + وضع URL اليدوي للخوادم البعيدة
- **OAuth Behind Nginx** — يستخدم `window.location.origin` للتوافق مع الوكيل العكسي
- **دليل OAuth عن بعد** — دليل خطوة بخطوة لبيانات اعتماد Google Cloud على VPS/Docker

</details>

<details>
<summary><b>📊 9. "لا أعرف كم أنفق أو أين"</b></summary>

يستخدم المطورون العديد من مقدمي الخدمات المدفوعة ولكن ليس لديهم رؤية موحدة للإنفاق. يمتلك كل مزود خدمة لوحة تحكم الفوترة الخاصة به، ولكن لا يوجد عرض موحد. التكاليف غير المتوقعة يمكن أن تتراكم.

**كيف يحل OmniRoute المشكلة:**

- **لوحة معلومات تحليلات التكلفة** — تتبع التكلفة لكل رمز مميز وإدارة الميزانية لكل مزود
- **حدود الميزانية لكل طبقة** — سقف الإنفاق لكل طبقة يؤدي إلى حدوث تراجع تلقائي
- **تكوين التسعير لكل نموذج** — أسعار قابلة للتكوين لكل نموذج- **إحصاءات الاستخدام لكل مفتاح API** — عدد الطلبات والطابع الزمني الأخير المستخدم لكل مفتاح
- **لوحة التحكم التحليلية** — بطاقات الإحصائيات، ومخطط استخدام النموذج، وجدول الموفر مع معدلات النجاح وزمن الاستجابة

</details>

<details>
<summary><b>🐛 10. "لا يمكنني تشخيص الأخطاء والمشكلات في مكالمات الذكاء الاصطناعي"</b></summary>

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

**كيف يحل OmniRoute المشكلة:**

- **لوحة تحكم السجلات الموحدة** — 4 علامات تبويب: سجلات الطلبات، وسجلات الوكيل، وسجلات التدقيق، ووحدة التحكم
- **عارض سجل وحدة التحكم** — عارض بنمط المحطة الطرفية في الوقت الفعلي مع مستويات مرمزة بالألوان، والتمرير التلقائي، والبحث، والتصفية
- **سجلات وكيل SQLite** — السجلات المستمرة التي تستمر حتى بعد إعادة تشغيل الخادم
- **ساحة المترجم** — 4 أوضاع لتصحيح الأخطاء: ساحة اللعب (ترجمة التنسيق)، اختبار الدردشة (ذهابًا وإيابًا)، منصة الاختبار (دفعة)، المراقبة المباشرة (في الوقت الفعلي)
- **قياس الطلب عن بعد** — زمن الاستجابة p50/p95/p99 + تتبع معرف طلب X
- **التسجيل المستند إلى الملف مع التدوير** — يلتقط جهاز اعتراض وحدة التحكم كل شيء إلى سجل JSON من خلال التدوير المستند إلى الحجم

</details>

<details>
<summary><b>🏗️ 11. "إن نشر البوابة وصيانتها أمر معقد"</b></summary>

يعد تثبيت وكيل AI وتكوينه وصيانته عبر بيئات مختلفة (محلية، VPS، Docker، سحابية) عملية كثيفة العمالة. مشاكل مثل المسارات المضمنة، `EACCES` في الدلائل، وتعارضات المنافذ، والبنيات عبر الأنظمة الأساسية تزيد من الاحتكاك.

**كيف يحل OmniRoute المشكلة:**

- **تثبيت npm الشامل** — `npm install -g omniroute && omniroute` — تم
- **منصة Docker المتعددة** — AMD64 + ARM64 الأصلي (Apple Silicon، AWS Graviton، Raspberry Pi)
- **ملفات تعريف Docker Compose** — `base` (لا توجد أدوات CLI) و`cli` (مع Claude Code وCodex وOpenClaw)
- **Electron Desktop App** — تطبيق أصلي لنظام التشغيل Windows/macOS/Linux مع علبة النظام، والتشغيل التلقائي، ووضع عدم الاتصال
- **وضع المنفذ المقسم** — واجهة برمجة التطبيقات ولوحة المعلومات على منافذ منفصلة للسيناريوهات المتقدمة (الوكيل العكسي، وشبكات الحاويات)
- **Cloud Sync** — مزامنة التكوين عبر الأجهزة عبر Cloudflare Workers
- **النسخ الاحتياطية لقاعدة البيانات** — النسخ الاحتياطي التلقائي لجميع الإعدادات واستعادتها وتصديرها واستيرادها

</details>

<details>
<summary><b>🌍 12. "الواجهة باللغة الإنجليزية فقط وفريقي لا يتحدث الإنجليزية"</b></summary>

تواجه الفرق في البلدان غير الناطقة باللغة الإنجليزية، وخاصة في أمريكا اللاتينية وآسيا وأوروبا، صعوبة في التعامل مع الواجهات التي تستخدم اللغة الإنجليزية فقط. تعمل حواجز اللغة على تقليل الاعتماد وزيادة أخطاء التكوين.

**كيف يحل OmniRoute المشكلة:**

- **لوحة المعلومات i18n — 30 لغة** — أكثر من 500 مفتاح مترجم بما في ذلك العربية والبلغارية والدنماركية والألمانية والإسبانية والفنلندية والفرنسية والعبرية والهندية والمجرية والإندونيسية والإيطالية واليابانية والكورية والماليزية والهولندية والنرويجية والبولندية والبرتغالية (PT/BR) والرومانية والروسية والسلوفاكية والسويدية والتايلاندية والأوكرانية والفيتنامية والصينية والفلبينية والإنجليزية
- **دعم RTL** — دعم من اليمين إلى اليسار للغتين العربية والعبرية
- **الملفات التمهيدية متعددة اللغات** — 30 ترجمة كاملة للوثائق
- **محدد اللغة** — رمز الكرة الأرضية في رأس الصفحة للتبديل في الوقت الفعلي</details>

<details>
<summary><b>🔄 13. "أحتاج إلى أكثر من مجرد الدردشة - أحتاج إلى التضمين والصور والصوت"</b></summary>

الذكاء الاصطناعي ليس مجرد استكمال للدردشة. يحتاج المطورون إلى إنشاء صور، ونسخ الصوت، وإنشاء تضمينات لـ RAG، وإعادة ترتيب المستندات، والإشراف على المحتوى. تحتوي كل واجهة برمجة تطبيقات على نقطة نهاية وتنسيق مختلفين.

**كيف يحل OmniRoute المشكلة:**

- **التضمينات** — `/v1/embeddings` مع 6 موفري خدمة وأكثر من 9 نماذج
- **إنشاء الصور** — `/v1/images/generations` مع 10 موفرين وأكثر من 20 نموذجًا (OpenAI، وxAI، وTogether، وFireworks، وNebius، وHyperbolic، وNanoBanana، وAntigravity، وSD WebUI، وComfyUI)
- **تحويل النص إلى فيديو** — `/v1/videos/generations` — ComfyUI (AnimateDiff، SVD) وSD WebUI
- **تحويل النص إلى موسيقى** — `/v1/music/generations` — ComfyUI (فتح الصوت الثابت، MusicGen)
- **النسخ الصوتي** — `/v1/audio/transcriptions` — Whisper + Nvidia NIM، HuggingFace، Qwen3
- **تحويل النص إلى كلام** — `/v1/audio/speech` — ElevenLabs، وNvidia NIM، وHuggingFace، وCoqui، وTortoise، وQwen3، بالإضافة إلى مقدمي الخدمات الحاليين
- **الإشراف** — `/v1/moderations` — التحقق من سلامة المحتوى
- **إعادة الترتيب** — `/v1/rerank` — إعادة ترتيب مدى ملاءمة المستند
- **Responses API** — دعم `/v1/responses` الكامل لـ Codex

</details>

<details>
<summary><b>🧪 14. "ليس لدي طريقة لاختبار ومقارنة الجودة عبر النماذج"</b></summary>

يرغب المطورون في معرفة النموذج الأفضل لحالة الاستخدام الخاصة بهم - التعليمات البرمجية، والترجمة، والتفكير - ولكن المقارنة يدويًا بطيئة. لا توجد أدوات تقييم متكاملة.

**كيف يحل OmniRoute المشكلة:**

- ** تقييمات LLM ** — اختبار المجموعة الذهبية مع 10 حالات محملة مسبقًا تغطي التحيات، والرياضيات، والجغرافيا، وإنشاء التعليمات البرمجية، والامتثال لـ JSON، والترجمة، وتخفيض السعر، والرفض الآمن
- **4 إستراتيجيات مطابقة** — `exact`، `contains`، `regex`، `custom` (وظيفة JS)
- **منصة اختبار ساحة المترجم** — اختبار الدفعات بمدخلات متعددة ومخرجات متوقعة، ومقارنة بين الموفرين
- **أداة اختبار الدردشة** — رحلة ذهابًا وإيابًا كاملة مع عرض الاستجابة المرئية
- **المراقبة المباشرة** — البث المباشر لجميع الطلبات المتدفقة عبر الوكيل

</details>

<details>
<summary><b>📈 15. "أحتاج إلى التوسع دون فقدان الأداء"</b></summary>

مع نمو حجم الطلب، يؤدي عدم التخزين المؤقت لنفس الأسئلة إلى توليد تكاليف مكررة. دون العجز، طلبات مكررة معالجة النفايات. يجب احترام حدود الأسعار لكل مزود.

**كيف يحل OmniRoute المشكلة:**

- **ذاكرة التخزين المؤقت الدلالية** — تعمل ذاكرة التخزين المؤقت ذات المستويين (التوقيع + الدلالي) على تقليل التكلفة ووقت الاستجابة
- **صلاحية الطلب** — نافذة إلغاء البيانات المكررة لمدة 5 ثوانٍ للطلبات المتماثلة
- **الكشف عن حدود المعدل** — عدد الدورات في الدقيقة لكل مزود، والفجوة الدنيا، والحد الأقصى للتتبع المتزامن
- **حدود المعدل القابلة للتحرير** — الإعدادات الافتراضية القابلة للتكوين في الإعدادات → المرونة مع الثبات
- **ذاكرة التخزين المؤقت للتحقق من صحة مفتاح واجهة برمجة التطبيقات** — ذاكرة تخزين مؤقت ثلاثية الطبقات لأداء الإنتاج
- **لوحة معلومات الصحة مع القياس عن بعد** — زمن الاستجابة p50/p95/p99، وإحصائيات ذاكرة التخزين المؤقت، ووقت التشغيل

</details>

<details>
<summary><b>🤖 16. "أريد التحكم في سلوك النموذج عالميًا"</b></summary>المطورون الذين يريدون جميع الاستجابات بلغة معينة، بنبرة معينة، أو يريدون الحد من الرموز المميزة للاستدلال. يعد تكوين هذا في كل أداة/طلب أمرًا غير عملي.

**كيف يحل OmniRoute المشكلة:**

- **الحقن الفوري للنظام** — يتم تطبيق المطالبة العامة على جميع الطلبات
- **التحقق من صحة ميزانية التفكير** — التحكم في تخصيص الرمز المميز لكل طلب (العبور، التلقائي، المخصص، التكيفي)
- **6 إستراتيجيات التوجيه** — إستراتيجيات عالمية تحدد كيفية توزيع الطلبات
- **Wildcard Router** — يتم توجيه أنماط `provider/*` ديناميكيًا إلى أي مزود
- **تبديل تمكين/تعطيل التحرير والسرد** — تبديل المجموعات مباشرة من لوحة المعلومات
- **تبديل الموفر** — تمكين/تعطيل جميع اتصالات الموفر بنقرة واحدة
- **المقدمون المحظورون** — استبعاد موفري الخدمة المحددين من قائمة `/v1/models`

</details>

<details>
<summary><b>🧰 17. "أحتاج إلى أدوات MCP كقدرات منتج من الدرجة الأولى"</b></summary>

تعرض العديد من بوابات الذكاء الاصطناعي MCP فقط كتفاصيل تنفيذ مخفية. تحتاج الفرق إلى طبقة تشغيل مرئية ويمكن التحكم فيها.

**كيف يحل OmniRoute المشكلة:**

- يظهر MCP في لوحة التحكم وعلامة تبويب بروتوكول نقطة النهاية
- صفحة إدارة MCP مخصصة تحتوي على العمليات والأدوات والنطاقات والتدقيق
- بداية سريعة مدمجة لـ `omniroute --mcp` وتأهيل العميل

</details>

<details>
<summary><b>🧠 18. "أحتاج إلى تنسيق A2A مع مسارات مهمة المزامنة + الدفق"</b></summary>

تحتاج مسارات عمل الوكيل إلى ردود مباشرة وتنفيذ متدفق طويل الأمد مع التحكم في دورة الحياة.

**كيف يحل OmniRoute المشكلة:**

- نقطة نهاية A2A JSON-RPC (`POST /a2a`) مع `message/send` و`message/stream`
- تدفق SSE مع انتشار الحالة الطرفية
- واجهات برمجة تطبيقات دورة حياة المهام لـ `tasks/get` و`tasks/cancel`

</details>

<details>
<summary><b>🛰️ 19. "أحتاج إلى صحة عملية MCP حقيقية، وليس حالة تخمينية"</b></summary>

تحتاج الفرق التشغيلية إلى معرفة ما إذا كان MCP حيًا بالفعل، وليس فقط ما إذا كان يمكن الوصول إلى واجهة برمجة التطبيقات (API).

**كيف يحل OmniRoute المشكلة:**

- ملف نبضات وقت التشغيل مع PID والطوابع الزمنية والنقل وعدد الأدوات ووضع النطاق
- واجهة برمجة تطبيقات حالة MCP التي تجمع بين نبضات القلب + النشاط الأخير
- بطاقات حالة واجهة المستخدم للعملية/وقت التشغيل/نضارة نبضات القلب

</details>

<details>
<summary><b>📋 20. "أحتاج إلى تنفيذ أداة MCP قابلة للتدقيق"</b></summary>

عندما تقوم الأدوات بتغيير التكوين أو تشغيل إجراءات العمليات، تحتاج الفرق إلى إمكانية التتبع الجنائي.

**كيف يحل OmniRoute المشكلة:**

- تسجيل التدقيق المدعوم من SQLite لاستدعاءات أداة MCP
- عوامل التصفية حسب الأداة، والنجاح/الفشل، ومفتاح API، وترقيم الصفحات
- جدول تدقيق لوحة المعلومات + إحصائيات نقاط النهاية للأتمتة

</details>

<details>
<summary><b>🔐 21. "أحتاج إلى أذونات MCP محددة النطاق لكل عملية تكامل"</b></summary>

يجب أن يتمتع العملاء المختلفون بإمكانية وصول أقل امتيازًا إلى فئات الأدوات.

**كيف يحل OmniRoute المشكلة:**

- 9 نطاقات MCP محببة للتحكم في الوصول إلى الأدوات
- إنفاذ النطاق والرؤية في واجهة مستخدم إدارة MCP
- الوضع الافتراضي الآمن للأدوات التشغيلية

</details>

<details><summary><b>⚙️ 22. "أحتاج إلى عناصر تحكم تشغيلية دون إعادة النشر"</b></summary>

تحتاج الفرق إلى تغييرات سريعة في وقت التشغيل أثناء الحوادث أو أحداث التكلفة.

**كيف يحل OmniRoute المشكلة:**

- قم بتبديل تنشيط التحرير والسرد مباشرةً من لوحة معلومات MCP
- تطبيق ملفات تعريف المرونة من حزم السياسات المحددة مسبقًا
- إعادة ضبط حالة قاطع الدائرة من نفس لوحة العمليات

</details>

<details>
<summary><b>🔄 23. "أحتاج إلى رؤية وإلغاء دورة حياة مهمة A2A المباشرة"</b></summary>

وبدون رؤية دورة الحياة، يصبح من الصعب فرز حوادث المهام.

**كيف يحل OmniRoute المشكلة:**

- قائمة المهام/التصفية حسب الحالة/المهارة مع ترقيم الصفحات
- التعمق في البيانات الوصفية للمهمة، والأحداث، والتحف
- نقطة نهاية إلغاء المهمة وإجراء واجهة المستخدم مع التأكيد

</details>

<details>
<summary><b>🌊 24. "أحتاج إلى مقاييس تيار نشطة لتحميل A2A"</b></summary>

يتطلب تدفق سير العمل رؤية تشغيلية للتزامن والاتصالات المباشرة.

**كيف يحل OmniRoute المشكلة:**

- عدادات التدفق النشطة مدمجة في حالة A2A
- الطابع الزمني للمهمة الأخيرة وعدد كل ولاية
- بطاقات لوحة القيادة A2A لمراقبة العمليات في الوقت الفعلي

</details>

<details>
<summary><b>🪪 25. "أحتاج إلى اكتشاف الوكيل القياسي للعملاء"</b></summary>

يحتاج العملاء والمنسقون الخارجيون إلى بيانات تعريف يمكن قراءتها آليًا من أجل الإعداد.

**كيف يحل OmniRoute المشكلة:**

- بطاقة الوكيل معروضة في `/.well-known/agent.json`
- القدرات والمهارات الموضحة في واجهة المستخدم الإدارية
- تتضمن واجهة برمجة التطبيقات لحالة A2A بيانات تعريف الاكتشاف للأتمتة

</details>

<details>
<summary><b>🧭 26. "أحتاج إلى إمكانية اكتشاف البروتوكول في تجربة المستخدم للمنتج"</b></summary>

إذا لم يتمكن المستخدمون من اكتشاف أسطح البروتوكول، فسوف ينخفض جودة الاعتماد والدعم.

**كيف يحل OmniRoute المشكلة:**

- إدخالات الشريط الجانبي لـ MCP وA2A
- علامة تبويب بروتوكولات صفحة نقطة النهاية مع البدء السريع والحالة
- روابط من النظرة العامة إلى لوحات معلومات الإدارة المخصصة

</details>

<details>
<summary><b>🧪 27. "أحتاج إلى التحقق من صحة البروتوكول الشامل مع عملاء حقيقيين"</b></summary>

الاختبارات الوهمية ليست كافية للتحقق من توافق البروتوكول قبل الإصدار.

**كيف يحل OmniRoute المشكلة:**

- مجموعة E2E التي تعمل على تشغيل التطبيق وتستخدم نقل عميل MCP SDK الحقيقي
- اختبارات عميل A2A لاكتشاف التدفقات وإرسالها ودفقها والحصول عليها وإلغائها
- التحقق من التأكيدات ضد تدقيق MCP وواجهات برمجة تطبيقات مهام A2A

</details>

<details>
<summary><b>📡 28. "أحتاج إلى إمكانية ملاحظة موحدة عبر جميع الواجهات"</b></summary>

يؤدي تقسيم إمكانية المراقبة حسب البروتوكول إلى إنشاء نقاط عمياء وMTTR أطول.

**كيف يحل OmniRoute المشكلة:**

- لوحات معلومات/سجلات/تحليلات موحدة في منتج واحد
- الصحة + التدقيق + طلب القياس عن بعد عبر طبقات OpenAI وMCP وA2A
- واجهات برمجة التطبيقات التشغيلية للحالة والأتمتة

</details>

<details>
<summary><b>💼 29. "أحتاج إلى وقت تشغيل واحد للوكيل + الأدوات + تنسيق الوكيل"</b></summary>

يؤدي تشغيل العديد من الخدمات المنفصلة إلى زيادة تكلفة التشغيل وأوضاع الفشل.

**كيف يحل OmniRoute المشكلة:**- وكيل متوافق مع OpenAI وخادم MCP وخادم A2A في مكدس واحد

- المصادقة المشتركة والمرونة وتخزين البيانات وإمكانية الملاحظة
- نموذج سياسة متسق عبر جميع أسطح التفاعل

</details>

<details>
<summary><b>🚀 30. "أحتاج إلى شحن عمليات سير عمل الوكيل دون امتداد كود الغراء"</b></summary>

تفقد الفرق سرعتها عند دمج العديد من الخدمات والبرامج النصية المخصصة.

**كيف يحل OmniRoute المشكلة:**

- استراتيجية نقطة النهاية الموحدة للعملاء والوكلاء
- واجهات مستخدم لإدارة البروتوكول مدمجة ومسارات التحقق من صحة الدخان
- أسس جاهزة للإنتاج (الأمان، التسجيل، المرونة، النسخ الاحتياطي)

</details>

### أمثلة لقواعد اللعبة (حالات الاستخدام المتكاملة)

** قواعد اللعبة أ: زيادة الاشتراك المدفوع إلى الحد الأقصى + نسخة احتياطية رخيصة **

```txt
Combo: "maximize-claude"
  1. cc/claude-opus-4-6
  2. glm/glm-4.7
  3. if/kimi-k2-thinking

Monthly cost: $20 + small backup spend
Outcome: higher quality, near-zero interruption
```

**دليل التشغيل ب: مكدس البرمجة بدون تكلفة**

```txt
Combo: "free-forever"
  1. gc/gemini-3-flash
  2. if/kimi-k2-thinking
  3. qw/qwen3-coder-plus

Monthly cost: $0
Outcome: stable free coding workflow
```

**Playbook C: سلسلة احتياطية تعمل دائمًا على مدار 24 ساعة طوال أيام الأسبوع**

```txt
Combo: "always-on"
  1. cc/claude-opus-4-6
  2. cx/gpt-5.2-codex
  3. glm/glm-4.7
  4. minimax/MiniMax-M2.1
  5. if/kimi-k2-thinking

Outcome: deep fallback depth for deadline-critical workloads
```

**قواعد اللعبة د: عمليات العميل مع MCP + A2A**

```txt
1) Start MCP transport (`omniroute --mcp`) for tool-driven operations
2) Run A2A tasks via `message/send` and `message/stream`
3) Observe via /dashboard/mcp and /dashboard/a2a
4) Control incidents with resilience profile + task cancellation
```

---

## ⚡ بداية سريعة

### 1) التثبيت والتشغيل

```bash
npm install -g omniroute
omniroute
```

يتم فتح لوحة المعلومات على `http://localhost:20128` ويكون عنوان URL الأساسي لواجهة برمجة التطبيقات هو `http://localhost:20128/v1`.

| الأمر                   | الوصف                                                                                 |
| ----------------------- | ------------------------------------------------------------------------------------- |
| `omniroute`             | بدء تشغيل الخادم (`PORT=20128` وواجهة برمجة التطبيقات ولوحة المعلومات على نفس المنفذ) |
| `omniroute --port 3000` | اضبط منفذ Canonical/API على 3000                                                      |
| `omniroute --mcp`       | بدء تشغيل خادم MCP (نقل stdio)                                                        |
| `omniroute --no-open`   | لا تفتح المتصفح تلقائيًا                                                              |
| `omniroute --help`      | عرض المساعدة                                                                          |

وضع المنفذ المقسم الاختياري:

```bash
PORT=20128 DASHBOARD_PORT=20129 omniroute
# API:       http://localhost:20128/v1
# Dashboard: http://localhost:20129
```

### 2) قم بتوصيل مقدمي الخدمة وإنشاء مفتاح واجهة برمجة التطبيقات (API) الخاص بك

1. افتح لوحة المعلومات → `Providers` وقم بتوصيل موفر واحد على الأقل (مفتاح OAuth أو API).
2. افتح لوحة المعلومات → `Endpoint` وقم بإنشاء مفتاح API.
3. (اختياري) افتح Dashboard → `Combos` وقم بتعيين السلسلة الاحتياطية.

### 3) قم بتوجيه أداة الترميز الخاصة بك إلى OmniRoute

```txt
Base URL: http://localhost:20128/v1
API Key:  [copy from Endpoint page]
Model:    if/kimi-k2-thinking (or any provider/model prefix)
```

يعمل مع Claude Code، وCodex CLI، وGemini CLI، وCursor، وCline، وOpenClaw، وOpenCode، وحزم SDK المتوافقة مع OpenAI.

### 4) تمكين البروتوكولات والتحقق من صحتها (الإصدار 2.0)

**MCP (للعمليات التي تعتمد على الأدوات):**

```bash
omniroute --mcp
```

ثم قم بتوصيل عميل MCP الخاص بك عبر `stdio` وأدوات الاختبار مثل:

-`omniroute_get_health` -`omniroute_list_combos`

**A2A (لسير العمل من وكيل إلى وكيل):**

```bash
curl http://localhost:20128/.well-known/agent.json
```

```bash
curl -X POST http://localhost:20128/a2a \
  -H 'content-type: application/json' \
  -d '{"jsonrpc":"2.0","id":"quickstart","method":"message/send","params":{"skill":"quota-management","messages":[{"role":"user","content":"Give me a short quota summary."}]}}'
```

### 5) التحقق من صحة كل شيء من البداية إلى النهاية (مستحسن)

```bash
npm run test:protocols:e2e
```

يتحقق هذا الجناح من تدفقات عميل MCP وA2A الحقيقية مقابل تطبيق قيد التشغيل.

### البديل: التشغيل من المصدر

```bash
cp .env.example .env
npm install
PORT=20128 DASHBOARD_PORT=20129 NEXT_PUBLIC_BASE_URL=http://localhost:20129 npm run dev
```

---

## 🐳 عامل الميناء

OmniRoute متاح كصورة Docker عامة على [Docker Hub](https://hub.docker.com/r/diegosouzapw/omniroute).

**الجري السريع:**

```bash
docker run -d \
  --name omniroute \
  --restart unless-stopped \
  -p 20128:20128 \
  -v omniroute-data:/app/data \
  diegosouzapw/omniroute:latest
```

** مع ملف البيئة: **

```bash
# Copy and edit .env first
cp .env.example .env

docker run -d \
  --name omniroute \
  --restart unless-stopped \
  --env-file .env \
  -p 20128:20128 \
  -v omniroute-data:/app/data \
  diegosouzapw/omniroute:latest
```

**استخدام Docker Compose:**

```bash
# Base profile (no CLI tools)
docker compose --profile base up -d

# CLI profile (Claude Code, Codex, OpenClaw built-in)
docker compose --profile cli up -d
```

| صورة                     | العلامة  | الحجم         | الوصف            |
| ------------------------ | -------- | ------------- | ---------------- |
| `diegosouzapw/omniroute` | `latest` | ~250 ميجابايت | أحدث إصدار مستقر |
| `diegosouzapw/omniroute` | `1.0.3`  | ~250 ميجابايت | النسخة الحالية   |

---

## 🖥️

قم بتشغيل OmniRoute كتطبيق مستقل لسطح المكتب - لا توجد محطة طرفية أو متصفح أو إنترنت مطلوب للطرز المحلية. يتضمن التطبيق المعتمد على Electron ما يلي:

- 🖥️ **النافذة الأصلية** — نافذة تطبيق مخصصة مع تكامل علبة النظام
- 🔄 **البدء التلقائي** — قم بتشغيل OmniRoute عند تسجيل الدخول إلى النظام
- 🔔 **الإشعارات الأصلية** — احصل على تنبيهات بشأن استنفاد الحصص أو مشكلات المزود
- ⚡ **التثبيت بنقرة واحدة** — NSIS (Windows)، DMG (macOS)، AppImage (Linux)
- 🌐 **وضع عدم الاتصال بالإنترنت** — يعمل بشكل كامل دون اتصال بالإنترنت مع الخادم المُجمَّع

### بداية سريعة

```bash
# Development mode
npm run electron:dev

# Build for your platform
npm run electron:build         # Current platform
npm run electron:build:win     # Windows (.exe)
npm run electron:build:mac     # macOS (.dmg) — x64 & arm64
npm run electron:build:linux   # Linux (.AppImage)
```

### علبة النظام

عند تصغيره، يظل OmniRoute موجودًا في علبة النظام لديك من خلال الإجراءات السريعة:

- فتح لوحة القيادة
- تغيير منفذ الخادم
- قم بإنهاء التطبيق

📖 التوثيق الكامل : [`electron/README.md`](electron/README.md)

---

## 💰 لمحة سريعة عن الأسعار

| الطبقة                             | مقدم                         | التكلفة                | إعادة ضبط الحصص         | الأفضل لـ                 |
| ---------------------------------- | ---------------------------- | ---------------------- | ----------------------- | ------------------------- |
| **💳الإشتراك**                     | كلود كود (برو)               | 20 دولارًا شهريًا      | 5 ساعات + أسبوعي        | اشتركت بالفعل             |
|                                    | الدستور الغذائي (زائد / برو) | 20-200 دولار شهريًا    | 5 ساعات + أسبوعي        | مستخدمي OpenAI            |
|                                    | الجوزاء CLI                  | **مجاني**              | 180 ألف/شهر + 1 ألف/يوم | الجميع!                   |
|                                    | جيثب مساعد الطيار            | 10-19 دولارًا شهريًا   | شهري                    | مستخدمي جيثب              |
| **🔑 مفتاح واجهة برمجة التطبيقات** | نفيديا نيم                   | **مجانًا** (1000 نقطة) | لمرة واحدة              | اختبار المستوى المجاني    |
|                                    | ديب سيك                      | الدفع لكل استخدام      | لا شيء                  | أفضل سعر/جودة             |
|                                    | جروك                         | طبقة مجانية + مدفوعة   | معدل محدود              | الاستدلال فائق السرعة     |
|                                    | xAI (جروك)                   | الدفع لكل استخدام      | لا شيء                  | نماذج جروك                |
|                                    | ميسترال                      | طبقة مجانية + مدفوعة   | معدل محدود              | الذكاء الاصطناعي الأوروبي |
|                                    | اوبن راوتر                   | الدفع لكل استخدام      | لا شيء                  | أكثر من 100 موديل         |
| **💰 رخيص**                        | جي إل إم-4.7                 | 0.6 دولار/1 مليون      | يوميا 10 صباحا          | نسخة احتياطية للميزانية   |
|                                    | ميني ماكس M2.1               | 0.2 دولار/1 مليون      | المتداول لمدة 5 ساعات   | الخيار الأرخص             |
|                                    | كيمي ك2                      | 9 دولارات شهريًا مسطحة | 10 مليون رمز/شهر        | التكلفة المتوقعة          |
| **🆓مجانًا**                       | اي فلو                       | $0                     | غير محدود               | 8 نماذج مجانية            |
|                                    | كوين                         | $0                     | غير محدود               | 3 نماذج مجانية            |
|                                    | كيرو                         | $0                     | غير محدود               | كلود مجاني                |

**💡 نصيحة احترافية:** ابدأ مع Gemini CLI (180 ألفًا مجانًا شهريًا) + مجموعة iFlow (مجانية غير محدودة) = تكلفة 0 دولار!

---

## 💡 الميزات الرئيسية

تم تصميم OmniRoute v2.0 كمنصة تشغيلية، وليس مجرد وكيل ترحيل.

### 🤖 عمليات الوكيل والبروتوكول (الإصدار 2.0)| ميزة | ماذا يفعل |

| ------------------------------------ | -------------------------------------------------------------------------------- |
| 🔧 **خادم MCP (16 أداة)** | تتحكم أدوات IDE/agent في التوجيه والصحة والمجموعات والحدود والعمليات | IDE/agent tools via 3 transports: stdio, SSE (`/api/mcp/sse`), Streamable HTTP (`/api/mcp/stream`)
| 🤝 **خادم A2A (JSON-RPC + SSE)** | تنفيذ المهام من وكيل إلى وكيل مع تدفقات المزامنة والتدفق |
| 🧭 **Consolidated Endpoints Page** | Tabbed management page with Endpoint Proxy, MCP, A2A, and API Endpoints tabs |
| 🎚️ **Service Enable/Disable Toggles** | ON/OFF switches for MCP and A2A with settings persistence (default: OFF) |
| 🛰️ **نبضات وقت تشغيل MCP** | حالة العملية الحقيقية (معرف المنتج، وقت التشغيل، عمر نبضات القلب، النقل، وضع النطاق) |
| 📋 **مسار تدقيق MCP** | سجلات التدقيق القابلة للتصفية مع النجاح/الفشل والإسناد الرئيسي |
| 🔐 **تنفيذ نطاق MCP** | 9 أذونات نطاق تفصيلية للوصول إلى الأدوات الخاضعة للرقابة |
| 📡 **إدارة دورة حياة المهام A2A** | قائمة/تصفية المهام، فحص الأحداث/التحف، إلغاء المهام قيد التشغيل |
| 📋 **اكتشاف بطاقة الوكيل** | `/.well-known/agent.json` للاكتشاف التلقائي للعميل |
| 🧪 **أداة اختبار البروتوكول E2E** | يتدفق عميل MCP SDK + A2A الحقيقي في `test:protocols:e2e` |
| ⚙️ **ضوابط التشغيل** | مجموعة التبديل، وتطبيق ملفات تعريف المرونة، وإعادة ضبط القواطع من سطح تحكم واحد |

### 🧠 التوجيه والاستخبارات

| ميزة                                      | ماذا يفعل                                                    |
| ----------------------------------------- | ------------------------------------------------------------ |
| 🎯 **احتياطي ذكي من 4 طبقات**             | المسار التلقائي: الاشتراك → مفتاح API → رخيص → مجاني         |
| 📊 **تتبع الحصص في الوقت الفعلي**         | عدد الرموز الحية + إعادة تعيين العد التنازلي لكل مزود        |
| 🔄 **تنسيق الترجمة**                      | OpenAI ↔ Claude ↔ Gemini ↔ الردود مع التحويلات الآمنة للمخطط |
| 👥 **دعم الحسابات المتعددة**              | حسابات متعددة لكل مزود مع اختيار ذكي                         |
| 🔄 **تحديث تلقائي للرمز**                 | يتم تحديث رموز OAuth المميزة تلقائيًا من خلال إعادة المحاولة |
| 🎨 **مجموعات مخصصة**                      | 6 استراتيجيات موازنة + التحكم في السلسلة الاحتياطية          |
| 🌐 **جهاز توجيه Wildcard**                | التوجيه الديناميكي `provider/*`                              |
| 🧠 **التفكير في ضوابط الميزانية**         | حدود التفكير المنطقي والتلقائي والمخصص والتكيفي              |
| 🔀 **الأسماء المستعارة للنماذج**          | مدمج + اسم مستعار للنموذج المخصص وأمان الترحيل               |
| ⚡ **تدهور الخلفية**                      | قم بتوجيه مهام الخلفية ذات الأولوية المنخفضة إلى نماذج أرخص  |
| 💬 **الحقن الفوري للنظام**                | يتم تطبيق ضوابط السلوك العالمية بشكل متسق                    |
| 📄 **توافق واجهة برمجة التطبيقات للردود** | دعم `/v1/responses` الكامل لـ Codex وسير عمل الوكلاء المتقدم |

### 🎵 واجهات برمجة التطبيقات متعددة الوسائط

| ميزة | ماذا يفعل || -------------------------- | ------------------------------------------------------------- |
| 🖼️ **إنشاء الصور** | `/v1/images/generations` مع الواجهات الخلفية السحابية والمحلية |
| 📐 **المضامين** | `/v1/embeddings` للبحث وخطوط أنابيب RAG |
| 🎤 **نسخ صوتي** | `/v1/audio/transcriptions` (مقدمو خدمات الهمس والإضافيون) |
| 🔊 **تحويل النص إلى كلام** | `/v1/audio/speech` (محركات/موفرو متعددون) |
| 🎬 **توليد الفيديو** | `/v1/videos/generations` (سير عمل ComfyUI + SD WebUI) |
| 🎵 **جيل الموسيقى** | `/v1/music/generations` (سير عمل ComfyUI) |
| 🛡️ **اعتدالات** | فحوصات السلامة `/v1/moderations` |
| 🔀 **إعادة الترتيب** | `/v1/rerank` لقياس مدى الملاءمة |

### 🛡️ المرونة والأمن والحوكمة

| ميزة                                                     | ماذا يفعل                                                             |
| -------------------------------------------------------- | --------------------------------------------------------------------- |
| 🔌 **قواطع الدائرة**                                     | رحلة/استرداد على مستوى الموفر مع عناصر التحكم في العتبة               |
| 🛡️ **القطيع المضاد للرعد**                               | حماية Mutex + الإشارة في أحداث إعادة المحاولة/التقييم                 |
| 🧠 ** ذاكرة التخزين المؤقت الدلالية + التوقيع **         | تقليل التكلفة/زمن الوصول باستخدام طبقتين من ذاكرة التخزين المؤقت      |
| ⚡ **طلب العجز**                                         | نافذة الحماية المكررة                                                 |
| 🔒 **انتحال بصمة الإصبع TLS**                            | توافق أفضل مع مقدمي خدمات مكافحة الروبوتات الذين تمت تصفيتهم          |
| 🌐 **تصفية IP**                                          | التحكم في القائمة المسموح بها/القائمة المحظورة لعمليات النشر المكشوفة |
| 📊 **حدود المعدل القابلة للتحرير**                       | حدود عالمية/مستوى مزود قابلة للتكوين مع الثبات                        |
| 🔑 **إدارة مفاتيح واجهة برمجة التطبيقات + تحديد النطاق** | تأمين إصدار/تدوير المفتاح وضوابط النموذج/المزود                       |
| 🛡️ **محمية `/models`**                                   | بوابة مصادقة اختيارية وإخفاء الموفر لكتالوج النماذج                   |

### 📊 إمكانية الملاحظة والتحليلات

| ميزة                             | ماذا يفعل                                                                 |
| -------------------------------- | ------------------------------------------------------------------------- |
| 📝 **الطلب + تسجيل الوكيل**      | الطلب/الاستجابة الكاملة وتسجيل الوكيل                                     |
| 📋 **لوحة تحكم السجلات الموحدة** | طلب العروض والوكيل والتدقيق ووحدة التحكم في صفحة واحدة                    |
| 🔍 **طلب القياس عن بعد**         | زمن الاستجابة p50/p95/p99 وطلب التتبع                                     |
| 🏥 **لوحة المعلومات الصحية**     | وقت التشغيل، حالات الكسارة، عمليات الإغلاق، إحصائيات ذاكرة التخزين المؤقت |
| 💰 **تتبع التكلفة**              | ضوابط الميزانية ورؤية التسعير لكل نموذج                                   |
| 📈 **تصورات التحليلات**          | رؤى استخدام النموذج/الموفر وطرق عرض الاتجاه                               |
| 🧪 **إطار التقييم**              | اختبار المجموعة الذهبية مع استراتيجيات المطابقة القابلة للتكوين           |

### ☁️ النشر والمنصة

| ميزة                             | ماذا يفعل                                        |
| -------------------------------- | ------------------------------------------------ | --- | ------------------------ | ------------------------------- |
| 🌐 **النشر في أي مكان**          | المضيف المحلي، VPS، Docker، البيئات السحابية     |     | 💾 **المزامنة السحابية** | مزامنة التكوين عبر عامل السحابة |
| 🔄 **النسخ الاحتياطي/الاستعادة** | تدفقات التصدير/الاستيراد والتعافي من الكوارث     |
| 🧙 **معالج الإعداد**             | الإعداد الموجه لأول مرة                          |
| 🔧 **لوحة تحكم أدوات CLI**       | إعداد بنقرة واحدة لأدوات الترميز الشائعة         |
| 🌐 **i18n (30 لغة)**             | لوحة تحكم كاملة + دعم لغة المستندات مع تغطية RTL |
| 📂 **دليل البيانات المخصصة**     | تجاوز `DATA_DIR` لموقع التخزين                   |

### ميزة الغوص العميق

#### إجراء احتياطي ذكي مع التحكم العملي في التكلفة

```txt
Combo: "my-coding-stack"
  1. cc/claude-opus-4-6
  2. nvidia/llama-3.3-70b
  3. glm/glm-4.7
  4. if/kimi-k2-thinking
```

عند فشل الحصة أو المعدل أو الصحة، ينتقل OmniRoute تلقائيًا إلى المرشح التالي دون التبديل اليدوي.

#### إدارة البروتوكول مرئية وقابلة للتشغيل

- يمكن اكتشاف MCP + A2A في واجهة المستخدم والمستندات (غير مخفية)
- تعرض واجهات برمجة التطبيقات لحالة البروتوكول بيانات التشغيل المباشرة (`/api/mcp/*`، `/api/a2a/*`)
- تتضمن لوحات المعلومات إجراءات لعمليات اليوم الثاني (تبديل التحرير والسرد، وإعادة ضبط الكسارة، وإلغاء المهام)

#### سير عمل المترجم + التحقق من الصحة

منطقة المترجم تشمل:

- **الملعب**: طلب عمليات التحقق من التحويل
- **أداة اختبار الدردشة**: الطلب/الإجابة الكاملة ذهابًا وإيابًا
- **منصة الاختبار**: حالات متعددة في جولة واحدة
- **المراقبة المباشرة**: عرض حركة المرور في الوقت الحقيقي

بالإضافة إلى التحقق من صحة البروتوكول مع عملاء حقيقيين عبر `npm run test:protocols:e2e`.

> 📖 **[قراءة خادم MCP](open-sse/mcp-server/README.md)** — مرجع الأداة، وتكوينات IDE، وأمثلة العميل
>
> 📖 **[ملف قراءة خادم A2A](src/lib/a2a/README.md)** — المهارات، وأساليب JSON-RPC، والبث، ودورة حياة المهمة

## 🧪 التقييمات (التقييمات)

يشتمل OmniRoute على إطار تقييم مدمج لاختبار جودة استجابة LLM مقابل المجموعة الذهبية. يمكنك الوصول إليه عبر **Analytics → Evals** في لوحة التحكم.

### الطقم الذهبي المدمج

تحتوي "OmniRoute Golden Set" المحملة مسبقًا على حالات اختبار لما يلي:

- تحياتي، الرياضيات، الجغرافيا، توليد التعليمات البرمجية
- الامتثال لتنسيق JSON والترجمة وإنشاء تخفيض السعر
- رفض السلامة (المحتوى الضار)، العد، المنطق المنطقي

### استراتيجيات التقييم

| استراتيجية | الوصف                                                         | مثال                             |
| ---------- | ------------------------------------------------------------- | -------------------------------- |
| `exact`    | يجب أن يتطابق الإخراج تمامًا مع                               | `"4"`                            |
| `contains` | يجب أن يحتوي الإخراج على سلسلة فرعية (غير حساسة لحالة الأحرف) | `"Paris"`                        |
| `regex`    | يجب أن يتطابق الإخراج مع نمط regex                            | `"1.*2.*3"`                      |
| `custom`   | ترجع دالة JS المخصصة صواب/خطأ                                 | `(output) => output.length > 10` |

---

## 📖 دليل الإعداد

### إعداد البروتوكول (MCP + A2A)

<details>
<summary><b>🧩 إعداد MCP (بروتوكول سياق النموذج)</b></summary>

بدء نقل MCP في وضع stdio:

```bash
omniroute --mcp
```

تدفق التحقق الموصى به:

1. قم بتوصيل عميل MCP الخاص بك عبر stdio.
2. قم بتشغيل `omniroute_get_health`.
3. قم بتشغيل `omniroute_list_combos`.
4. افتح `/dashboard/mcp` لتأكيد نبضات القلب والنشاط والتدقيق.

واجهات برمجة التطبيقات المفيدة للأتمتة:

-`GET /api/mcp/status` -`GET /api/mcp/tools` -`GET /api/mcp/audit` -`GET /api/mcp/audit/stats`

</details>

<details><summary><b>🤝 إعداد A2A (Agent2Agent)</b></summary>

اكتشف الوكيل:

```bash
curl http://localhost:20128/.well-known/agent.json
```

إرسال مهمة:

```bash
curl -X POST http://localhost:20128/a2a \
  -H 'content-type: application/json' \
  -d '{"jsonrpc":"2.0","id":"setup-a2a","method":"message/send","params":{"skill":"quota-management","messages":[{"role":"user","content":"Summarize quota status."}]}}'
```

إدارة دورة الحياة:

-`GET /api/a2a/status` -`GET /api/a2a/tasks` -`GET /api/a2a/tasks/:id` -`POST /api/a2a/tasks/:id/cancel`

واجهة المستخدم التشغيلية:

- `/dashboard/a2a` لإمكانية ملاحظة المهمة/الحالة/الدفق وإجراءات الدخان

</details>

<details>
<summary><b>🧪 التحقق من صحة البروتوكول من طرف إلى طرف</b></summary>

التحقق من صحة كلا البروتوكولين مع عملاء حقيقيين:

```bash
npm run test:protocols:e2e
```

هذا يتحقق:

- اتصال/قائمة/اتصال عميل MCP SDK
- اكتشاف A2A/إرسال/دفق/حصول على/إلغاء
- التحقق من البيانات في تدقيق MCP وواجهات برمجة التطبيقات لإدارة المهام A2A

</details>

<details>
<summary><b>💳 مقدمي الاشتراك</b></summary>

### كلود كود (برو/ماكس)

```bash
Dashboard → Providers → Connect Claude Code
→ OAuth login → Auto token refresh
→ 5-hour + weekly quota tracking

Models:
  cc/claude-opus-4-6
  cc/claude-sonnet-4-5-20250929
  cc/claude-haiku-4-5-20251001
```

**نصيحة احترافية:** استخدم Opus للمهام المعقدة، وSonnet للسرعة. OmniRoute يتتبع الحصة لكل نموذج!

### OpenAI Codex (Plus/Pro)

```bash
Dashboard → Providers → Connect Codex
→ OAuth login (port 1455)
→ 5-hour + weekly reset

Models:
  cx/gpt-5.2-codex
  cx/gpt-5.1-codex-max
```

### Gemini CLI (180 ألفًا شهريًا مجانًا!)

```bash
Dashboard → Providers → Connect Gemini CLI
→ Google OAuth
→ 180K completions/month + 1K/day

Models:
  gc/gemini-3-flash-preview
  gc/gemini-2.5-pro
```

**أفضل قيمة:** طبقة مجانية ضخمة! استخدم هذا قبل المستويات المدفوعة.

### مساعد جيثب

```bash
Dashboard → Providers → Connect GitHub
→ OAuth via GitHub
→ Monthly reset (1st of month)

Models:
  gh/gpt-5
  gh/claude-4.5-sonnet
  gh/gemini-3-pro
```

</details>

<details>
<summary><b>🔑 موفري مفاتيح واجهة برمجة التطبيقات</b></summary>

### NVIDIA NIM (1000 نقطة مجانية!)

1. قم بالتسجيل: [build.nvidia.com](https://build.nvidia.com)
2. احصل على مفتاح واجهة برمجة التطبيقات (API) مجانًا (يتضمن 1000 نقطة استدلال)
3. لوحة المعلومات → إضافة موفر → NVIDIA NIM:
   - مفتاح API: `nvapi-your-key`

**النماذج:** `nvidia/llama-3.3-70b-instruct` و`nvidia/mistral-7b-instruct` وأكثر من 50 طرازًا آخر

**نصيحة احترافية:** واجهة برمجة التطبيقات المتوافقة مع OpenAI — تعمل بسلاسة مع ترجمة تنسيق OmniRoute!

### ديب سيك

1. قم بالتسجيل: [platform.deepseek.com](https://platform.deepseek.com)
2. احصل على مفتاح API
3. لوحة المعلومات → إضافة موفر → DeepSeek

**النماذج:** `deepseek/deepseek-chat`, `deepseek/deepseek-coder`

### Groq (الطبقة المجانية متاحة!)

1. قم بالتسجيل: [console.groq.com](https://console.groq.com)
2. احصل على مفتاح API (الطبقة المجانية متضمنة)
3. لوحة المعلومات → إضافة موفر → Groq

**النماذج:** `groq/llama-3.3-70b`, `groq/mixtral-8x7b`

**نصيحة احترافية:** استنتاج فائق السرعة — الأفضل للبرمجة في الوقت الفعلي!

### OpenRouter (+100 موديل)

1. قم بالتسجيل: [openrouter.ai](https://openrouter.ai)
2. احصل على مفتاح API
3. لوحة المعلومات → إضافة موفر → OpenRouter

**النماذج:** يمكنك الوصول إلى أكثر من 100 نموذج من جميع المزودين الرئيسيين من خلال مفتاح واجهة برمجة التطبيقات (API) واحد.

</details>

<details>
<summary><b>💰 مقدمو الخدمة الرخيصة (النسخ الاحتياطي)</b></summary>

### GLM-4.7 (إعادة التعيين اليومي، 0.6 دولار/1 مليون)

1. قم بالتسجيل: [Zhipu AI](https://open.bigmodel.cn/)
2. احصل على مفتاح API من خطة الترميز
3. لوحة المعلومات → إضافة مفتاح واجهة برمجة التطبيقات:
   - المزود: `glm`
   - مفتاح API: `your-key`

**الاستخدام:** `glm/glm-4.7`

**نصيحة احترافية:** توفر خطة البرمجة حصة 3× بتكلفة 1/7! إعادة الضبط يوميًا الساعة 10:00 صباحًا.

### MiniMax M2.1 (إعادة الضبط لمدة 5 ساعات، 0.20 دولار/1 مليون)

1. قم بالتسجيل: [MiniMax](https://www.minimax.io/)
2. احصل على مفتاح API
3. لوحة المعلومات → إضافة مفتاح API

**الاستخدام:** `minimax/MiniMax-M2.1`

**نصيحة احترافية:** الخيار الأرخص للسياق الطويل (مليون رمز)!

### كيمي K2 (شقة بقيمة 9 دولارات شهريًا)

1. الاشتراك: [Moonshot AI](https://platform.moonshot.ai/)
2. احصل على مفتاح API
3. لوحة المعلومات → إضافة مفتاح API

**الاستخدام:** `kimi/kimi-latest`

**نصيحة احترافية:** سعر ثابت قدره 9 دولارات شهريًا مقابل 10 ملايين رمز مميز = 0.90 دولارًا أمريكيًا/مليون تكلفة فعالة!

</details>

<details>
<summary><b>🆓 موفري الخدمة المجانية (النسخ الاحتياطي في حالات الطوارئ)</b></summary>

### iFlow (8 نماذج مجانية)```bash

Dashboard → Connect iFlow
→ iFlow OAuth login
→ Unlimited usage

Models:
if/kimi-k2-thinking
if/qwen3-coder-plus
if/glm-4.7
if/minimax-m2
if/deepseek-r1

````

### كوين (3 موديلات مجانية)

```bash
Dashboard → Connect Qwen
→ Device code authorization
→ Unlimited usage

Models:
  qw/qwen3-coder-plus
  qw/qwen3-coder-flash
````

### كيرو (كلود فري)

```bash
Dashboard → Connect Kiro
→ AWS Builder ID or Google/GitHub
→ Unlimited usage

Models:
  kr/claude-sonnet-4.5
  kr/claude-haiku-4.5
```

</details>

<details>
<summary><b>🎨 إنشاء المجموعات</b></summary>

### مثال 1: زيادة الاشتراك إلى الحد الأقصى → النسخ الاحتياطي الرخيص

```
Dashboard → Combos → Create New

Name: premium-coding
Models:
  1. cc/claude-opus-4-6 (Subscription primary)
  2. glm/glm-4.7 (Cheap backup, $0.6/1M)
  3. minimax/MiniMax-M2.1 (Cheapest fallback, $0.20/1M)

Use in CLI: premium-coding
```

### المثال 2: مجاني فقط (بدون تكلفة)

```
Name: free-combo
Models:
  1. gc/gemini-3-flash-preview (180K free/month)
  2. if/kimi-k2-thinking (unlimited)
  3. qw/qwen3-coder-plus (unlimited)

Cost: $0 forever!
```

</details>

<details>
<summary><b>🔧 تكامل CLI</b></summary>

### بيئة تطوير متكاملة للمؤشر

```
Settings → Models → Advanced:
  OpenAI API Base URL: http://localhost:20128/v1
  OpenAI API Key: [from OmniRoute dashboard]
  Model: cc/claude-opus-4-6
```

### كلود كود

استخدم صفحة **أدوات CLI** في لوحة المعلومات للتكوين بنقرة واحدة، أو قم بتحرير `~/.claude/settings.json` يدويًا.

### كوديكس سطر الأوامر

```bash
export OPENAI_BASE_URL="http://localhost:20128"
export OPENAI_API_KEY="your-omniroute-api-key"

codex "your prompt"
```

### OpenClaw

**الخيار 1 — لوحة التحكم (مستحسن):**

```
Dashboard → CLI Tools → OpenClaw → Select Model → Apply
```

**الخيار 2 — يدويًا:** تحرير `~/.openclaw/openclaw.json`:

```json
{
  "models": {
    "providers": {
      "omniroute": {
        "baseUrl": "http://127.0.0.1:20128/v1",
        "apiKey": "sk_omniroute",
        "api": "openai-completions"
      }
    }
  }
}
```

> **ملاحظة:** يعمل OpenClaw فقط مع OmniRoute المحلي. استخدم `127.0.0.1` بدلاً من `localhost` لتجنب مشكلات دقة IPv6.

### كلاين / متابعة / RooCode

```
Settings → API Configuration:
  Provider: OpenAI Compatible
  Base URL: http://localhost:20128/v1
  API Key: [from OmniRoute dashboard]
  Model: if/kimi-k2-thinking
```

### الكود المفتوح

**الخطوة 1:** أضف OmniRoute كموفر مخصص:

```bash
opencode
/connect
# Select "Other" → Enter ID: "omniroute" → Enter your OmniRoute API key
```

**الخطوة 2:** إنشاء/تحرير `opencode.json` في جذر مشروعك:

```json
{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "omniroute": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "OmniRoute",
      "options": {
        "baseURL": "http://localhost:20128/v1"
      },
      "models": {
        "cc/claude-sonnet-4-20250514": { "name": "Claude Sonnet 4" },
        "gg/gemini-2.5-pro": { "name": "Gemini 2.5 Pro" },
        "if/kimi-k2-thinking": { "name": "Kimi K2 (Free)" }
      }
    }
  }
}
```

**الخطوة 3:** حدد النموذج في OpenCode:

```bash
/models
# Select any OmniRoute model from the list
```

> **نصيحة:** أضف أي نموذج متوفر في نقطة نهاية OmniRoute `/v1/models` إلى قسم `models`. استخدم التنسيق `provider/model-id` من لوحة معلومات OmniRoute.

</details>

---

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

<details>
<summary><b>انقر لتوسيع دليل استكشاف الأخطاء وإصلاحها</b></summary>

**"نموذج اللغة لم يقدم رسائل"**

- استنفدت حصة الموفر → تحقق من تعقب حصة الموفر في لوحة المعلومات
- الحل: استخدم خيار التحرير والسرد الاحتياطي أو قم بالتبديل إلى مستوى أرخص

** الحد من المعدل **

- حصة الاشتراك المحددة → الرجوع إلى GLM/MiniMax
- إضافة التحرير والسرد: `cc/claude-opus-4-6 → glm/glm-4.7 → if/kimi-k2-thinking`

** انتهت صلاحية رمز OAuth **

- يتم التحديث تلقائيًا بواسطة OmniRoute
- إذا استمرت المشكلات: لوحة المعلومات → الموفر → إعادة الاتصال

**تكاليف مرتفعة**

- التحقق من إحصائيات الاستخدام في لوحة المعلومات → التكاليف
- تبديل النموذج الأساسي إلى GLM/MiniMax
- استخدم الطبقة المجانية (Gemini CLI، iFlow) للمهام غير الحرجة

**منافذ لوحة المعلومات/واجهة برمجة التطبيقات غير صحيحة**

- `PORT` هو المنفذ الأساسي الأساسي (ومنفذ API افتراضيًا)
- يتجاوز `API_PORT` مستمع واجهة برمجة التطبيقات (API) المتوافق مع OpenAI فقط
- يتجاوز `DASHBOARD_PORT` مستمع لوحة المعلومات/Next.js فقط
- قم بتعيين `NEXT_PUBLIC_BASE_URL` على لوحة المعلومات/عنوان URL العام (لعمليات الاسترجاعات عبر OAuth)

**أخطاء المزامنة السحابية**

- تحقق من نقاط `BASE_URL` لمثيلك قيد التشغيل
- تحقق من نقاط `CLOUD_URL` إلى نقطة النهاية السحابية المتوقعة
- حافظ على محاذاة قيم `NEXT_PUBLIC_*` مع القيم من جانب الخادم

**تسجيل الدخول الأول لا يعمل**

- تحقق من `INITIAL_PASSWORD` في `.env`
- في حالة عدم تعيينها، تكون كلمة المرور الاحتياطية هي `123456`

** لا توجد سجلات الطلب **

- تعيين `ENABLE_REQUEST_LOGS=true` في `.env`

**يظهر اختبار الاتصال "غير صالح" لمقدمي الخدمات المتوافقين مع OpenAI**

- لا يكشف العديد من مقدمي الخدمة عن نقطة نهاية `/models`
- يتضمن OmniRoute v1.0.6+ التحقق الاحتياطي من خلال إكمال الدردشة
- تأكد من أن عنوان URL الأساسي يتضمن لاحقة `/v1`

### 🔐 OAuth

<a name="oauth-em-servidor-remoto"></a>

> **⚠️ هام لمستخدمي OmniRoute على VPS/Docker/servidor عن بعد**

#### OAuth

نظرًا لأن اعتمادات OAuth المُدخلة ليست في OmniRoute، فهي عبارة عن سجلات **apenas لـ `localhost`**. عندما تصل إلى OmniRoute من خادم بعيد (على سبيل المثال: `https://omniroute.meuservidor.com`)، تحصل Google على مصادقة عبر:

```
Error 400: redirect_uri_mismatch
```

#### الحل: تكوين OAuth الخاص بك

يجب عليك إنشاء **OAuth 2.0 Client ID** على Google Cloud Console باستخدام URI لخادمك.

#### باسو باسو

**1. الوصول إلى Google Cloud Console**

العبرة: [https://console.cloud.google.com/apis/credentials](https://console.cloud.google.com/apis/credentials)

**2. طلب معرف عميل OAuth 2.0 **

- انقر على **"+ إنشاء بيانات الاعتماد"** → **"معرف عميل OAuth"**
- نوع التطبيق: **"تطبيق ويب"**
- الاسم: اسم escolha qualquer (على سبيل المثال: `OmniRoute Remote`)

**3. Adicione كمحددات URI لإعادة التوجيه المعتمدة**

ليس هناك مجال **"عناوين URI لإعادة التوجيه المعتمدة"**، أضف:

```
https://seu-servidor.com/callback
```

> استبدال `seu-servidor.com` بنطاقك أو IP بخادمك (بما في ذلك البوابة الضرورية، على سبيل المثال: `http://45.33.32.156:20128/callback`).

**4. حفظ ونسخ كمعتمدة**

وبعد ذلك، قم بإنشاء أو عرض Google o **معرف العميل** أو **سر العميل**.

**5. تكوين كمتغيرات البيئة **

ليس لديك `.env` (أو في بيئة Docker المتنوعة):

```bash
# Para Antigravity:
ANTIGRAVITY_OAUTH_CLIENT_ID=seu-client-id.apps.googleusercontent.com
ANTIGRAVITY_OAUTH_CLIENT_SECRET=GOCSPX-seu-secret

# Para Gemini CLI:
GEMINI_OAUTH_CLIENT_ID=seu-client-id.apps.googleusercontent.com
GEMINI_OAUTH_CLIENT_SECRET=GOCSPX-seu-secret
GEMINI_CLI_OAUTH_CLIENT_SECRET=GOCSPX-seu-secret
```

**6. Reinicie أو OmniRoute**

```bash
# Se usando npm:
npm run dev

# Se usando Docker:
docker restart omniroute
```

**7. خيمة تواصل جديدة**

لوحة المعلومات → الموفرون → Antigravity (ou Gemini CLI) → OAuth

قم بإعادة توجيه Google بشكل صحيح إلى `https://seu-servidor.com/callback` ووظيفة المصادقة.

---

#### الحل المؤقت (لم يتم تكوين الاعتمادات الخاصة)

إذا لم ترغب في إنشاء بيانات اعتماد خاصة بك منذ الآن، فمن الممكن استخدام التدفق **دليل URL**:

1. يفتح OmniRoute عنوان URL لتفويض Google
2. قم بتفويض Google لإعادة توجيه `localhost` (لا يوجد خادم عن بعد)
3. **انسخ عنوان URL كاملاً** من شريط الإدخال في متصفحك (حتى لا يتم نقل الصفحة)
4. هذا هو عنوان URL الذي يظهر في وضع الاتصال بـ OmniRoute
5. انقر على **"الاتصال"**

> يعمل هذا الحل البديل لأن رمز التفويض الموجود على عنوان URL يكون صالحًا بشكل مستقل لإعادة التوجيه حيث يتم تحميله أو لا.

</details>

---

## 🛠️

<details>
<summary><b>انقر لتوسيع تفاصيل حزمة التقنية</b></summary>

- **وقت التشغيل**: Node.js 18–22 LTS (⚠️ Node.js 24+ **غير مدعومة** — الثنائيات الأصلية `better-sqlite3` غير متوافقة)
- **اللغة**: TypeScript 5.9 — **TypeScript بنسبة 100%** عبر `src/` و`open-sse/` (لا يوجد `any` في الوحدات الأساسية منذ الإصدار 2.0)
- **الإطار**: Next.js 16 + React 19 + Tailwind CSS 4
- **قاعدة البيانات**: LowDB (JSON) + SQLite (حالة المجال + سجلات الوكيل + تدقيق MCP + قرارات التوجيه)
- **المخططات**: Zod (التحقق من صحة الإدخال/الإخراج لأداة MCP، وعقود API)
- **البروتوكولات**: MCP (stdio/HTTP) + A2A v0.3 (JSON-RPC 2.0 + SSE)
- **البث**: الأحداث المرسلة من الخادم (SSE)
- **المصادقة**: OAuth 2.0 (PKCE) + JWT + مفاتيح API + ترخيص نطاق MCP
- **الاختبار**: مشغل اختبار Node.js + Vitest (أكثر من 900 اختبار بما في ذلك الوحدة والتكامل وE2E)- **CI/CD**: إجراءات GitHub (نشر npm التلقائي + Docker Hub عند الإصدار)
- **الموقع الإلكتروني**: [omniroute.online](https://omniroute.online)
- **الحزمة**: [npmjs.com/package/omniroute](https://www.npmjs.com/package/omniroute)
- **دوكر**: [hub.docker.com/r/diegosouzapw/omniroute](https://hub.docker.com/r/diegosouzapw/omniroute)
- **المرونة**: قاطع الدائرة، والتراجع الأسي، وقطيع مكافحة الرعد، وانتحال TLS، والإصلاح الذاتي للتحرير والسرد التلقائي

</details>

---

## 📖 التوثيق

| وثيقة                                               | الوصف                                                 |
| --------------------------------------------------- | ----------------------------------------------------- |
| [دليل المستخدم](docs/USER_GUIDE.md)                 | مقدمو الخدمات، والمجموعات، وتكامل CLI، والنشر         |
| [مرجع واجهة برمجة التطبيقات](docs/API_REFERENCE.md) | جميع نقاط النهاية مع الأمثلة                          |
| [خادم MCP](open-sse/mcp-server/README.md)           | 16 أدوات MCP وتكوينات IDE وعملاء Python/TS/Go         |
| [خادم A2A](src/lib/a2a/README.md)                   | بروتوكول JSON-RPC 2.0، المهارات، التدفق، إدارة المهام |
| [محرك التحرير والسرد التلقائي](docs/auto-combo.md)  | تسجيل 6 عوامل، حزم الوضع، الشفاء الذاتي               |
| [استكشاف الأخطاء وإصلاحها](docs/TROUBLESHOOTING.md) | المشاكل والحلول الشائعة                               |
| [الهندسة المعمارية](docs/ARCHITECTURE.md)           | بنية النظام والداخلية                                 |
| [مساهمة](CONTRIBUTING.md)                           | إعداد التطوير والمبادئ التوجيهية                      |
| [مواصفات OpenAPI](docs/openapi.yaml)                | مواصفات OpenAPI 3.0                                   |
| [سياسة الأمان](SECURITY.md)                         | الإبلاغ عن الثغرات الأمنية والممارسات الأمنية         |
| [نشر الجهاز الافتراضي](docs/VM_DEPLOYMENT_GUIDE.md) | الدليل الكامل: إعداد VM + nginx + Cloudflare          |
| [معرض الميزات](docs/FEATURES.md)                    | جولة لوحة القيادة المرئية مع لقطات الشاشة             |
| [قائمة مراجعة الإصدار](docs/RELEASE_CHECKLIST.md)   | خطوات التحقق من صحة الإصدار المسبق                    |

---

## 🗺️خريطة الطريق

يحتوي OmniRoute على **210+ ميزات مخطط لها** عبر مراحل تطوير متعددة. فيما يلي المجالات الرئيسية:

| الفئة                       | الميزات المخططة | أبرز الأحداث                                                                                                                                  |
| --------------------------- | --------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| 🧠 **التوجيه والاستخبارات** | 25+             | التوجيه ذو زمن الاستجابة الأقل، والتوجيه القائم على العلامات، والاختبار المبدئي للحصة، واختيار حساب P2C                                       |
| 🔒 **الأمان والامتثال**     | 20+             | تقوية SSRF، وإخفاء بيانات الاعتماد، والحد الأقصى للمعدل لكل نقطة نهاية، وتحديد نطاق مفتاح الإدارة                                             |
| 📊 **قابلية الملاحظة**      | 15+             | تكامل OpenTelemetry ومراقبة الحصص في الوقت الفعلي وتتبع التكلفة لكل نموذج                                                                     |
| 🔄 **تكامل الموفر**         | 20+             | تسجيل النموذج الديناميكي، فترات تهدئة الموفر، الدستور الغذائي متعدد الحسابات، تحليل حصة الطيار المساعد                                        |
| ⚡ **الأداء**               | 15+             | طبقة ذاكرة التخزين المؤقت المزدوجة، ذاكرة التخزين المؤقت السريعة، ذاكرة التخزين المؤقت للاستجابة، استمرار البث، واجهة برمجة التطبيقات الدفعية |
| 🌐 **النظام البيئي**        | 10+             | WebSocket API، إعادة تحميل التكوين السريع، مخزن التكوين الموزع، الوضع التجاري                                                                 |

### 🔜قريبا- 🔗 **تكامل OpenCode** — دعم الموفر الأصلي لـ OpenCode AI IDE للترميز

- 🔗 **تكامل TRAE** — الدعم الكامل لإطار تطوير TRAE AI
- 📦 **Batch API** — معالجة الدفعات غير المتزامنة للطلبات المجمعة
- 🎯 **التوجيه المعتمد على العلامات** — توجيه الطلبات بناءً على العلامات المخصصة والبيانات الوصفية
- 💰 **إستراتيجية أقل تكلفة** — تحديد أرخص مزود متاح تلقائيًا

> 📝 مواصفات الميزات الكاملة متوفرة في [`docs/new-features/`](docs/new-features/) (217 مواصفات تفصيلية)

---

## 👥 المساهمون

[![المساهمون](https://contrib.rocks/image?repo=diegosouzapw/OmniRoute&max=100&columns=20&anon=1)](https://github.com/diegosouzapw/OmniRoute/graphs/contributors)

### كيفية المساهمة

1. شوكة المستودع
2. قم بإنشاء فرع الميزات الخاص بك (`git checkout -b feature/amazing-feature`)
3. تنفيذ التغييرات (`git commit -m 'Add amazing feature'`)
4. ادفع إلى الفرع (`git push origin feature/amazing-feature`)
5. افتح طلب السحب

راجع [CONTRIBUTING.md](CONTRIBUTING.md) للحصول على إرشادات مفصلة.

### إطلاق نسخة جديدة

```bash
# Create a release — npm publish happens automatically
gh release create v2.0.0 --title "v2.0.0" --generate-notes
```

---

## 📊 تاريخ النجوم

<a href="https://star-history.com/#diegosouzapw/OmniRoute&Date">
 <picture>
   <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=diegosouzapw/OmniRoute&type=Date&theme=dark" />
   <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=diegosouzapw/OmniRoute&type=Date" />
   <img alt="Star History Chart" src="https://api.star-history.com/svg?repos=diegosouzapw/OmniRoute&type=Date" />
 </picture>
</a>

---

## 🙏 شكر وتقدير

شكر خاص لـ **[9router](https://github.com/decolua/9router)** بواسطة **[decolua](https://github.com/decolua)** — المشروع الأصلي الذي ألهم هذه الشوكة. يعتمد OmniRoute على هذا الأساس المذهل مع ميزات إضافية وواجهات برمجة التطبيقات متعددة الوسائط وإعادة كتابة TypeScript كاملة.

شكر خاص لـ **[CLIProxyAPI](https://github.com/router-for-me/CLIProxyAPI)** — تطبيق Go الأصلي الذي ألهم منفذ JavaScript هذا.

---

## 📄 الترخيص

ترخيص MIT - راجع [الترخيص](LICENSE) للحصول على التفاصيل.

---

<div align="center">
  <sub> تم تصميمه باستخدام ❤️ للمطورين الذين يبرمجون 24/7</sub>
  <br/>
  <sub><a href="https://omniroute.online">omniroute.online</a></sub>
</div>
<!-- GitHub Discussions enabled for community Q&A -->
