# CLI Tools — OmniRoute (العربية)

🌐 **Languages:** 🇺🇸 [English](../../../../reference/CLI-TOOLS.md) · 🇪🇹 [am](../../../am/docs/reference/CLI-TOOLS.md) · 🇦🇿 [az](../../../az/docs/reference/CLI-TOOLS.md) · 🇧🇬 [bg](../../../bg/docs/reference/CLI-TOOLS.md) · 🇧🇩 [bn](../../../bn/docs/reference/CLI-TOOLS.md) · 🇧🇦 [bs](../../../bs/docs/reference/CLI-TOOLS.md) · 🇨🇿 [cs](../../../cs/docs/reference/CLI-TOOLS.md) · 🇩🇰 [da](../../../da/docs/reference/CLI-TOOLS.md) · 🇩🇪 [de](../../../de/docs/reference/CLI-TOOLS.md) · 🇬🇷 [el](../../../el/docs/reference/CLI-TOOLS.md) · 🇪🇸 [es](../../../es/docs/reference/CLI-TOOLS.md) · 🇪🇪 [et](../../../et/docs/reference/CLI-TOOLS.md) · 🇮🇷 [fa](../../../fa/docs/reference/CLI-TOOLS.md) · 🇫🇮 [fi](../../../fi/docs/reference/CLI-TOOLS.md) · 🇫🇷 [fr](../../../fr/docs/reference/CLI-TOOLS.md) · 🇮🇪 [ga](../../../ga/docs/reference/CLI-TOOLS.md) · 🇮🇳 [gu](../../../gu/docs/reference/CLI-TOOLS.md) · 🇳🇬 [ha](../../../ha/docs/reference/CLI-TOOLS.md) · 🇮🇱 [he](../../../he/docs/reference/CLI-TOOLS.md) · 🇮🇳 [hi](../../../hi/docs/reference/CLI-TOOLS.md) · 🇭🇷 [hr](../../../hr/docs/reference/CLI-TOOLS.md) · 🇭🇺 [hu](../../../hu/docs/reference/CLI-TOOLS.md) · 🇦🇲 [hy](../../../hy/docs/reference/CLI-TOOLS.md) · 🇮🇩 [id](../../../id/docs/reference/CLI-TOOLS.md) · 🇳🇬 [ig](../../../ig/docs/reference/CLI-TOOLS.md) · 🇮🇹 [it](../../../it/docs/reference/CLI-TOOLS.md) · 🇯🇵 [ja](../../../ja/docs/reference/CLI-TOOLS.md) · 🇬🇪 [ka](../../../ka/docs/reference/CLI-TOOLS.md) · 🇰🇭 [km](../../../km/docs/reference/CLI-TOOLS.md) · 🇮🇳 [kn](../../../kn/docs/reference/CLI-TOOLS.md) · 🇰🇷 [ko](../../../ko/docs/reference/CLI-TOOLS.md) · 🇱🇹 [lt](../../../lt/docs/reference/CLI-TOOLS.md) · 🇱🇻 [lv](../../../lv/docs/reference/CLI-TOOLS.md) · 🇮🇳 [ml](../../../ml/docs/reference/CLI-TOOLS.md) · 🇮🇳 [mr](../../../mr/docs/reference/CLI-TOOLS.md) · 🇲🇾 [ms](../../../ms/docs/reference/CLI-TOOLS.md) · 🇲🇹 [mt](../../../mt/docs/reference/CLI-TOOLS.md) · 🇲🇲 [my](../../../my/docs/reference/CLI-TOOLS.md) · 🇳🇵 [ne](../../../ne/docs/reference/CLI-TOOLS.md) · 🇳🇱 [nl](../../../nl/docs/reference/CLI-TOOLS.md) · 🇳🇴 [no](../../../no/docs/reference/CLI-TOOLS.md) · 🇮🇳 [or](../../../or/docs/reference/CLI-TOOLS.md) · 🇮🇳 [pa](../../../pa/docs/reference/CLI-TOOLS.md) · 🇵🇭 [phi](../../../phi/docs/reference/CLI-TOOLS.md) · 🇵🇱 [pl](../../../pl/docs/reference/CLI-TOOLS.md) · 🇵🇹 [pt](../../../pt/docs/reference/CLI-TOOLS.md) · 🇧🇷 [pt-BR](../../../pt-BR/docs/reference/CLI-TOOLS.md) · 🇷🇴 [ro](../../../ro/docs/reference/CLI-TOOLS.md) · 🇷🇺 [ru](../../../ru/docs/reference/CLI-TOOLS.md) · 🇱🇰 [si](../../../si/docs/reference/CLI-TOOLS.md) · 🇸🇰 [sk](../../../sk/docs/reference/CLI-TOOLS.md) · 🇸🇮 [sl](../../../sl/docs/reference/CLI-TOOLS.md) · 🇷🇸 [sr](../../../sr/docs/reference/CLI-TOOLS.md) · 🇸🇪 [sv](../../../sv/docs/reference/CLI-TOOLS.md) · 🇰🇪 [sw](../../../sw/docs/reference/CLI-TOOLS.md) · 🇮🇳 [ta](../../../ta/docs/reference/CLI-TOOLS.md) · 🇮🇳 [te](../../../te/docs/reference/CLI-TOOLS.md) · 🇹🇭 [th](../../../th/docs/reference/CLI-TOOLS.md) · 🇹🇷 [tr](../../../tr/docs/reference/CLI-TOOLS.md) · 🇺🇦 [uk-UA](../../../uk-UA/docs/reference/CLI-TOOLS.md) · 🇵🇰 [ur](../../../ur/docs/reference/CLI-TOOLS.md) · 🇺🇿 [uz](../../../uz/docs/reference/CLI-TOOLS.md) · 🇻🇳 [vi](../../../vi/docs/reference/CLI-TOOLS.md) · 🇳🇬 [yo](../../../yo/docs/reference/CLI-TOOLS.md) · 🇨🇳 [zh-CN](../../../zh-CN/docs/reference/CLI-TOOLS.md) · 🇹🇼 [zh-TW](../../../zh-TW/docs/reference/CLI-TOOLS.md)

---

آخر تحديث: 2026-08-23

تتكامل OmniRoute مع ثلاث فئات من أدوات CLI المنتشرة عبر ثلاث صفحات مخصصة للوحة المعلومات:

| صفحة          | طريق                    | مفهوم                                                                     | عدد          |
| ------------- | ----------------------- | ------------------------------------------------------------------------- | ------------ |
| **كود CLI**   | `/dashboard/cli-code`   | أدوات البرمجة التي تشير إليها OmniRoute (العميل → CLI → OmniRoute → موفر) | 26           |
| **وكلاء CLI** | `/dashboard/cli-agents` | الوكلاء المستقلون الذين تشير إليهم OmniRoute (نفس التدفق، ونطاق أوسع)     | 11           |
| **وكلاء ACP** | `/dashboard/acp-agents` | CLIs الذي يولد OmniRoute كواجهة خلفية عبر stdio/ACP (التدفق العكسي)       | انظر التسجيل |

يتم إعادة توجيه المسارات القديمة عبر 308: `/dashboard/cli-tools` → `/dashboard/cli-code` و `/dashboard/agents` → `/dashboard/acp-agents`.

---

## آلية العمل

```
أدوات CLI البرمجية / وكلاء CLI (تدفق الاستهلاك):
Claude / Codex / OpenCode / Cline / KiloCode / Continue / Hermes Agent / Goose / ...
           │
           ▼  (تشير جميعها إلى OmniRoute)
    http://YOUR_SERVER:20128/v1
           │
           ▼  (يوجّه OmniRoute الطلب إلى المزوّد المناسب)
    Anthropic / OpenAI / Gemini / DeepSeek / Groq / Mistral / ...

وكلاء ACP (تدفق التشغيل العكسي):
    طلب العميل ← OmniRoute ← يشغّل CLI عبر stdio/ACP ← الاستجابة
```

**الفوائد:**

- مفتاح API واحد لإدارة جميع الأدوات
- تتبع التكلفة لجميع أدوات CLI في لوحة المعلومات
- تبديل النماذج دون إعادة تهيئة كل أداة
- يعمل محليًا وعلى الخوادم البعيدة (VPS وDocker وAkamai وCloudflare Tunnel)

---

## التكوين التلقائي مع `setup-*`

ليس عليك كتابة تكوين كل أداة يدويًا. يقوم OmniRoute بشحن أمر `setup-*` لكل CLI مدعوم يقرأ ملف** يعيش** كتالوج النموذج من OmniRoute قيد التشغيل (محلي أو بعيد) ويكتب التكوين الخاص بالأداة على جهازك:

```bash
omniroute setup-codex        omniroute setup-claude       omniroute setup-opencode
omniroute setup-cline        omniroute setup-kilo         omniroute setup-continue
omniroute setup-cursor       omniroute setup-roo          omniroute setup-crush
omniroute setup-goose        omniroute setup-qwen         omniroute setup-aider
omniroute setup-5dive        omniroute setup-zed
omniroute setup-whycodes
```

يقبل كل منها `--remote <url> --api-key <key>` (تكوين أداة محلية مقابل OmniRoute عن بعد)، `--dry-run` (معاينة بدون كتابة)، و `--port`. الأدوات التي لا تحتوي على الاكتشاف التلقائي للنماذج (Cline و Kilo و Roo و Goose و Aider و Qwen و 5dive و WhyCodes) تأخذ `--model <id>` (و `--yes` لعمليات التشغيل غير التفاعلية). `setup-5dive` هي الوصفة الوحيدة التي لا تُكتب تحت `$HOME`: فهي تقوم بتكوين أسطول وكلاء 5dive عن طريق كتابة ملف تعريف مصادقة مملوك للجذر على مضيف الأسطول، لذلك يتم إعادة تنفيذه من خلال `sudo` وليس لديه وضع بعيد خاص به. لإطلاق CLI مع حقن البيئة الصحيحة وعدم كتابة أي تكوين على الإطلاق، استخدم مشغل `omniroute run <target>` العام (claude، codex، aider، goose، opencode، qwen،gemini، Whycodes - الأهداف والأسماء المستعارة تأتي من `bin/cli/cli-manifest.mjs`)؛ تظل أدوات الإطلاق القديمة لكل أداة `omniroute launch` (رمز Claude ) و `omniroute launch-codex` (Codex) متاحة. Gemini CLI هو إطلاق فقط: إنه هدف `omniroute run` ولكن لا يحتوي على وصفة `setup-*`/`configure`.

> **المرجع الكامل:** الجدول الرئيسي - ما يكتبه كل أمر، كل علم، محلي مقابل بعيد، والأدوات التي تريد لاحقة `/v1` - موجود في** [التكامل CLI](../guides/CLI-INTEGRATIONS.md)** .

### تشغيل هذه داخل حاوية

يتم تنفيذ أمر `setup-*` داخل حاوية OmniRoute ويكتب في الصفحة الرئيسية للحاوية، والتي لا يقرأها أي مضيف CLI والتي تختفي مع الحاوية. يكتشف OmniRoute ذلك ويخرج من `2` بالتعليمات بدلاً من الكتابة. هناك طريقتان مدعومتان للمضي قدمًا - تثبيت CLI على المضيف و `omniroute connect` على الحاوية، أو ربط تثبيت config dirs وتعيين `CLI_CONFIG_HOME` (ملف تعريف `host` للإنشاء). كل أمر `setup-*` ، بالإضافة إلى `omniroute configure` و `omniroute config set`، يقبل `--allow-container-write` عندما يكون تكوين CLIs الخاص بالحاوية هو ما تقصده بالفعل؛ `OMNIROUTE_ALLOW_CONTAINER_CONFIG_WRITE=true` يفعل نفس الشيء بالنسبة للخادم. راجع [دليل Docker → تكوين أدوات المضيف CLI](../guides/DOCKER_GUIDE.md#configuring-host-cli-tools-when-omniroute-runs-in-docker).

لوحة القيادة** تطبيق نقطة النهاية** (`POST /api/cli-tools/apply`) يفرض نفس الحراسة: في الحاوية، الكتابة التي لا يتم ربط هدفها من المضيف تجيب**`422`** باستخدام `containerEphemeralTarget: true`، نص الخطأ الآمن و- بالنسبة للأدوات التي تحتوي على وصفة مضيف (claude، codex، opencode، cline، Kilo، continue) - `hostSetupCommand` (على سبيل المثال `omniroute setup-opencode`) للتشغيل على المضيف بدلاً من ذلك؛ لم يتم كتابة أي شيء. يستمر `dryRun: true` في العمل في وضع الحاوية ويعيد مسار هدف + للمعاينة المنقحة دون لمس القرص. لا تعد معاينة المحتوى تكوينًا يحمل بيانات الاعتماد للنسخ أو الاستيراد. قم بالتطبيق باستخدام مدخلات tool/base URL/API key/model الأصلية على المضيف، أو استخدم أمر الإعداد من جانب المضيف المشار إليه. راجع [أمان تكوين CLI](../security/CLI-CONFIGURATION.md) لرأس المعاينة وطلب العقد. هذا السلوك مقصود ومحمي من الانحدار بواسطة `tests/unit/api/cli-tools/apply-container-guard.test.ts` - لا "تصلح" 422 أبدًا عن طريق إزالة الحماية.

---

## مصدر الحقيقة

يوجد الكتالوج الموحّد في `src/shared/constants/cliTools.ts` باسم `CLI_TOOLS: Record<string, CliCatalogEntry>`.

يحتوي كل إدخال على الحقول التالية (المعرّفة في `src/shared/schemas/cliCatalog.ts`):

| الحقل                                           | النوع                                                        | الوصف                                                       |
| ----------------------------------------------- | ------------------------------------------------------------ | ----------------------------------------------------------- |
| `category`                                      | `"code" \| "agent"`                                          | الصفحة التي تظهر فيها الأداة                                |
| `vendor`                                        | `string`                                                     | مصدر الأداة ("Anthropic"، "OSS (P. Gauthier)")              |
| `acpSpawnable`                                  | `boolean`                                                    | يمكن استخدامها أيضًا كوكيل ACP (تظهر شارة)                  |
| `baseUrlSupport`                                | `"full" \| "partial" \| "none"`                              | مستوى دعم نقطة النهاية المخصّصة. `"none"` = قائمة مهام MITM |
| `configType`                                    | `"env" \| "custom" \| "guide" \| "custom-builder" \| "mitm"` | آلية التكوين                                                |
| `id`, `name`, `color`, `description`, `docsUrl` | قياسي                                                        | حقول العرض الأساسية                                         |

الإدخالات التي تحتوي على `baseUrlSupport: "none"` **لا تظهر** في صفحات لوحة المعلومات — بل تُسجّل في قائمة مهام MITM الخاصة بالخطة 11 (راجع `_tasks/features-v3.8.6/refactorpages/_orchestration/_plan11-mitm-backlog.md`).

### مستويات القدرات (مفهرسة × قابلة للاكتشاف × قابلة للتكوين × قابلة للتشغيل)

ليست كل أداة مفهرسة قابلة للاكتشاف أو التكوين أو التشغيل. لكل مستوى
مصدر واحد يعلنه، ويحافظ اختبار الانحراف على اتساقها:

| المستوى            | المعنى                                                                       | مُعلن عنه في                                                       |
| ------------------ | ---------------------------------------------------------------------------- | ------------------------------------------------------------------ |
| **مفهرسة**         | تظهر في كتالوج لوحة المعلومات (الاسم، والمورّد، والوثائق، ونوع التكوين)      | `src/shared/constants/cliTools.ts` (`CLI_TOOLS`)                   |
| **قابلة للاكتشاف** | اكتشاف الملف الثنائي/التكوين، وفحوصات السلامة، ومسارات التكوين               | `src/shared/services/cliRuntime.ts` (كتالوج وقت تشغيل `CLI_TOOLS`) |
| **قابلة للتكوين**  | مدعومة بواسطة `omniroute configure <cli>` (توجد وصفة إعداد)                  | `bin/cli/cli-manifest.mjs` (`configure: true`)                     |
| **قابلة للتشغيل**  | مدعومة بواسطة `omniroute run <target>` (تم تعريف حقن متغيرات البيئة/الوسائط) | `bin/cli/cli-manifest.mjs` (`run: true`)                           |

يُعد `bin/cli/cli-manifest.mjs` بيان التنفيذ المرجعي لواجهات أوامر CLI:
تستمد منه `run` و`configure` ومولّدات الإكمال الطرفي جميعُها
قوائم الأهداف، وتحليل الأسماء البديلة (مثل `kilocode`/`kilo-code`/`kilo_cli` → `kilo`)
وإعداد علامة `--model`. يتحقق حاجز الانحراف
`tests/unit/cli/cli-manifest-drift.test.ts` من بقاء البيان وكتالوج وقت التشغيل
وكتالوج واجهة المستخدم وكل واجهة مستهلكة متزامنة — وتؤدي إضافة هدف إلى
واجهة واحدة دون الواجهات الأخرى إلى فشل مجموعة الاختبارات بدلًا من حدوث انحراف بصمت.

---

## 1. كتالوج CLI Code (28 أداة)

جميع الأدوات التي تظهر في `/dashboard/cli-code`. يتم توصيل الأشخاص الذين لديهم `baseUrlSupport: none` عبر MITM أو دليل يدوي بدلاً من قاعدة مخصصة URL:

| بطاقة تعريف    | اسم                      | بائع                  | baseUrlSupport | configType | acpSpawnable |
| -------------- | ------------------------ | --------------------- | -------------- | ---------- | ------------ |
| كلود           | كود Claude               | Anthropic             | ممتلىء         | بيئة       | حقيقي        |
| المخطوطة       | OpenAI Codex CLI         | OpenAI                | ممتلىء         | مخصص       | حقيقي        |
| com.zcode      | ZCode (خطة الترميز GLM ) | Z.ai                  | لا أحد         | مخصص       | خطأ شنيع     |
| كلاين          | Cline                    | OSS (كلود ديف سابقًا) | ممتلىء         | مخصص       | حقيقي        |
| كيلو           | كود الكيلو               | كيلو-Org              | ممتلىء         | مخصص       | خطأ شنيع     |
| رو             | كود رو                   | رو (OSS)              | ممتلىء         | مرشد       | خطأ شنيع     |
| يكمل           | يكمل                     | continue.dev          | ممتلىء         | مرشد       | خطأ شنيع     |
| مساعد          | مساعد                    | OSS (ب. غوتييه)       | ممتلىء         | مرشد       | حقيقي        |
| صياغة          | ForgeCode                | تناقض HQ              | ممتلىء         | مخصص       | حقيقي        |
| jcode          | jcode                    | 1جيهوانغ (OSS)        | ممتلىء         | مخصص       | خطأ شنيع     |
| Deepseek-tui   | DeepSeek TUI             | هانتر باون (OSS)      | ممتلىء         | مخصص       | خطأ شنيع     |
| الحوت الكودي   | CodeWhale                | همبون (OSS)           | ممتلىء         | مخصص       | خطأ شنيع     |
| opencode       | OpenCode                 | شذوذ (SST سابقًا)     | ممتلىء         | مرشد       | حقيقي        |
| الروبوت        | الروبوت المصنع           | مصنع AI               | جزئي           | مرشد       | خطأ شنيع     |
| مساعد الطيار   | GitHub Copilot CLI       | GitHub/MS             | ممتلىء         | مخصص       | خطأ شنيع     |
| المؤشر CLI     | Cursor CLI               | في أي مكان            | جزئي           | مرشد       | حقيقي        |
| الهف           | الهف                     | ليونارد سيسر (OSS)    | ممتلىء         | مخصص       | خطأ شنيع     |
| باي            | Pi (عامل ترميز pi)       | م. زيتشنر (OSS)       | ممتلىء         | مخصص       | خطأ شنيع     |
| grok-build     | بناء Grok                | xAI                   | ممتلىء         | مخصص       | خطأ شنيع     |
| معجب           | معجب                     | OSS (سحر)             | ممتلىء         | مخصص       | خطأ شنيع     |
| كوين           | كود Qwen                 | Alibaba               | ممتلىء         | مرشد       | حقيقي        |
| com.openclaude | OpenClaude               | جيتلاوب (OSS)         | ممتلىء         | مرشد       | خطأ شنيع     |
| زيد            | Zed                      | صناعات Zed            | ممتلىء         | مرشد       | خطأ شنيع     |
| المؤشر         | Cursor                   | في أي مكان            | لا أحد         | مرشد       | خطأ شنيع     |
| مضاد الجاذبية  | Antigravity              | Google                | لا أحد         | ميتم       | خطأ شنيع     |
| هيرميس         | هيرميس                   | أبحاث نوس             | لا أحد         | مرشد       | خطأ شنيع     |
| كيرو           | Kiro AI                  | Amazon                | لا أحد         | ميتم       | خطأ شنيع     |
| مخصص           | CLI مخصصة                | —                     | ممتلىء         | منشئ مخصص  | خطأ شنيع     |

تعرض الأدوات التي تحتوي على `baseUrlSupport: "partial"` شارة "⚠ Base URL parcial" في بطاقة لوحة القيادة.
---

## 2. كتالوج وكلاء CLI (11 أداة)

الوكلاء المستقلون الذين يظهرون في `/dashboard/cli-agents`:

| بطاقة تعريف    | اسم              | بائع               | baseUrlSupport | com.acpSpawnable |
| -------------- | ---------------- | ------------------ | -------------- | ---------------- |
| وكيل هيرميس    | وكيل هيرميس      | أبحاث نوس          | ممتلىء         | خطأ شنيع         |
| openclaw       | OpenClaw         | OSS (ب. شتاينبرجر) | ممتلىء         | حقيقي            |
| أوزة           | أوزة             | مؤسسة كتلة/ Linux  | ممتلىء         | حقيقي            |
| مترجم          | افتح المترجم     | OSS                | ممتلىء         | حقيقي            |
| انفتل          | Warp AI          | شركة Warp          | جزئي           | حقيقي            |
| سطح السفينة    | وكيل سطح السفينة | اشيشجوبلاني (OSS)  | ممتلىء         | خطأ شنيع         |
| com.omp        | يا ماي بي        | OSS                | ممتلىء         | حقيقي            |
| Letta          | ليتا CLI         | ليتا               | ممتلىء         | خطأ شنيع         |
| الوكيل الرئيسي | الوكيل الرئيسي   | رئيس الفكر (OSS)   | ممتلىء         | خطأ شنيع         |
| 5dive          | 5dive            | OSS (5dive-ai)     | ممتلىء         | خطأ شنيع         |
| howcodes       | WhyCodes         | لماذا شركة         | ممتلىء         | خطأ شنيع         |

---

## 3. وكلاء ACP (/dashboard/acp-agents)

تعرض هذه الصفحة (التي أُعيدت تسميتها من `/dashboard/agents`) واجهات CLI التي يمكن لـ OmniRoute **تشغيلها** كمحركات تنفيذ خلفية عبر بروتوكول stdio/ACP. تتم صيانة الكتالوج بصورة منفصلة في `src/lib/acp/registry.ts`، وهو **ليس** مماثلًا لـ `CLI_TOOLS`.

---

## 4. قائمة MITM المؤجلة (لا تظهر في لوحة المعلومات)

لا تدعم واجهات CLI التالية عنوان URL أساسيًا مخصصًا بصورة أصلية، وهي **غير مدرجة** في صفحتي CLI Code أو CLI Agents. وهي مرشحة للاعتراض عبر MITM في الخطة 11:

| CLI                 | السبب                                                   |
| ------------------- | ------------------------------------------------------- |
| windsurf            | يقتصر BYOK على نماذج Claude محددة + عنوان URL/رمز مؤسسي |
| amp                 | منظومة مغلقة (Sourcegraph)                              |
| amazon-q / kiro-cli | مصادقة AWS SSO، دون عنوان URL مخصص                      |
| cowork              | Anthropic Desktop، دون نقطة نهاية قابلة للتهيئة         |

راجع `_tasks/features-v3.8.6/refactorpages/_orchestration/_plan11-mitm-backlog.md` للاطلاع على الإحالات المرجعية الكاملة.

---

## 5. واجهة API للكشف الدفعي

تُجمّع جميع عمليات اكتشاف الأدوات عبر نقطة نهاية واحدة:

**`GET /api/cli-tools/all-statuses`**

- المصادقة: `requireCliToolsAuth(request)` (كما هو الحال مع مسارات `/api/cli-tools/` الأخرى)
- القيمة المُعادة: `Record<toolId, ToolBatchStatus>` (النوع: `src/shared/types/cliBatchStatus.ts`)
- الاستراتيجية: `Promise.all` عبر جميع الأدوات، مع مهلة 5 ثوانٍ لكل أداة
- ذاكرة التخزين المؤقت: LRU داخل الذاكرة، مفهرسة حسب `mtime` لملف الإعداد. تُبطَل ذاكرة التخزين المؤقت عند تغيّر mtime. وتُعاد تهيئتها عند إعادة تشغيل الخادم.

بنية الاستجابة لكل أداة:

```ts
interface ToolBatchStatus {
  detection: {
    installed: boolean;
    runnable: boolean;
    version?: string;
    command?: string;
    commandPath?: string;
    reason?: string;
  };
  config: {
    status: "configured" | "not_configured" | "not_installed" | "unknown" | "other";
    endpoint?: string | null;
    lastConfiguredAt?: string | null;
  };
  error?: string; // منقّح، دون تتبعات للمكدس
}
```

---

## 6. معالجات الإعدادات للأدوات الجديدة

الأدوات الجديدة مع `configType: "custom"` لها إعدادات مخصصة لمسارات API :

| طريق                                        | أداة                                                             |
| ------------------------------------------- | ---------------------------------------------------------------- |
| `POST /api/cli-tools/forge-settings`        | ForgeCode (.forge.toml)                                          |
| `POST /api/cli-tools/jcode-settings`        | جي كود (علم --base-url )                                         |
| `POST /api/cli-tools/deepseek-tui-settings` | DeepSeek TUI (OPENAI_BASE_URL، تراث)                             |
| `POST /api/cli-tools/codewhale-settings`    | CodeWhale (OPENAI_BASE_URL, primary + legacy `~/.deepseek` sync) |
| `POST /api/cli-tools/smelt-settings`        | الهف                                                             |
| `POST /api/cli-tools/pi-settings`           | وكيل ترميز Pi (`~/.pi/agent/models.json`، `providers.omniroute`) |
| `POST /api/cli-tools/grok-build-settings`   | Grok Build (~/.grok/config.toml, `[model.omniroute]`)            |
| `POST /api/cli-tools/qwen-settings`         | كود Qwen (`~/.qwen/settings.json` + مفتاح `.env` مخصص)           |

تستخدم جميع المسارات `sanitizeErrorMessage()` للاستجابات للأخطاء (القاعدة الصعبة رقم 12).

---

## 7. بنية صفحات لوحة المعلومات

### أكواد CLI (`/dashboard/cli-code`)

- `src/app/(dashboard)/dashboard/cli-code/page.tsx` — مكوّن خادم
- `src/app/(dashboard)/dashboard/cli-code/CliCodePageClient.tsx` — شبكة عميل
- `src/app/(dashboard)/dashboard/cli-code/[id]/page.tsx` — صفحة تفاصيل الأداة
- `src/app/(dashboard)/dashboard/cli-code/components/` — 12 بطاقة أدوات متخصصة + `ToolDetailClient.tsx`

### وكلاء CLI (`/dashboard/cli-agents`)

- `src/app/(dashboard)/dashboard/cli-agents/page.tsx` — مكوّن خادم
- `src/app/(dashboard)/dashboard/cli-agents/CliAgentsPageClient.tsx` — شبكة عميل
- `src/app/(dashboard)/dashboard/cli-agents/[id]/page.tsx` — يعيد استخدام `ToolDetailClient`

### وكلاء ACP (`/dashboard/acp-agents`)

- `src/app/(dashboard)/dashboard/acp-agents/page.tsx` — مكوّن خادم (نُقل من `agents/`)

### مكوّنات واجهة المستخدم المشتركة (`src/shared/components/cli/`)

| الملف                   | الغرض                                               |
| ----------------------- | --------------------------------------------------- |
| `CliToolCard.tsx`       | بطاقة حالة ذكية (الاكتشاف + الإعداد + نقطة النهاية) |
| `CliConceptCard.tsx`    | بطاقة شرح المفهوم لكل صفحة                          |
| `CliComparisonCard.tsx` | مقارنة من ثلاثة أعمدة بين أنواع CLI                 |
| `BaseUrlSelect.tsx`     | قائمة منسدلة لنقطة النهاية (محلية/سحابية/مخصصة)     |
| `ApiKeySelect.tsx`      | محدد مفتاح API                                      |
| `ManualConfigModal.tsx` | نافذة منبثقة لمقتطف إعداد قابل للنسخ                |

### الخطّاف المشترك (`src/shared/hooks/cli/`)

| الملف                     | الغرض                                                         |
| ------------------------- | ------------------------------------------------------------- |
| `useToolBatchStatuses.ts` | يجلب `/api/cli-tools/all-statuses` ويدير حالة التحميل/التحديث |

---

## 8. التدويل

أُضيفت مساحات أسماء جديدة في الخطة 14 F9:

| مساحة الاسم | الغرض                                                                            |
| ----------- | -------------------------------------------------------------------------------- |
| `cliCommon` | النصوص المشتركة (تسميات البطاقات، نصوص المفاهيم/المقارنات، تسميات صفحة التفاصيل) |
| `cliCode`   | نصوص صفحة CLI Code                                                               |
| `cliAgents` | نصوص صفحة CLI Agents                                                             |
| `acpAgents` | نصوص صفحة ACP Agents                                                             |

تتوفر ترجمات كاملة للبرتغالية البرازيلية والإنجليزية. وتعود اللغات الـ39 الأخرى تلقائيًا إلى الإنجليزية عبر الدمج على مستوى مساحة الاسم في `src/i18n/request.ts`.

---

## 9. البداية السريعة

### الخطوة 1 — احصل على مفتاح OmniRoute API

1. افتح `/dashboard/api-manager` →** إنشاء مفتاح API**
2. أعطه اسمًا (على سبيل المثال `cli-tools`) وحدد كافة الأذونات
3. انسخ المفتاح — الذي ستحتاج إليه لكل CLI أدناه

> يبدو مفتاحك مثل: `sk-xxxxxxxxxxxxxxxx-xxxxxxxxx`

---

### الخطوة 2 — تثبيت أدوات CLI

تتطلب جميع الأدوات المستندة إلى npm Node.js 22.22.2 + أو 24.x:

```bash
# Claude Code (Anthropic)
npm install -g @anthropic-ai/claude-code

# OpenAI Codex
npm install -g @openai/codex

# OpenCode
npm install -g opencode-ai

# Cline
npm install -g cline

# KiloCode
npm install -g kilocode

# Qwen Code
npm install -g @qwen-code/qwen-code

# Google Gemini CLI (launchable via `omniroute run gemini` → /v1beta surface)
npm install -g @google/gemini-cli

# Aider
pip install aider-chat

# Smelt
cargo install smelt  # Rust-based

# Pi coding agent
npm install -g --ignore-scripts @earendil-works/pi-coding-agent

# jcode
# see https://github.com/1jehuang/jcode for install
```

---

### الخطوة 3 — قم بالتكوين عبر لوحة المعلومات

1. اذهب الى `http://localhost:20128/dashboard/cli-code`
2. ابحث عن أداتك في الشبكة
3. انقر فوق البطاقة لفتح صفحة تفاصيل الأداة
4. حدد مفتاح API وقاعدة URL
5. انقر** تطبيق التكوين** أو انسخ مقتطف التكوين اليدوي

---

### الخطوة 4 — قم بتعيين متغيرات البيئة العالمية

```bash
# OmniRoute Universal Endpoint
export OPENAI_BASE_URL="http://localhost:20128/v1"
export OPENAI_API_KEY="sk-your-omniroute-key"
export ANTHROPIC_BASE_URL="http://localhost:20128"
export ANTHROPIC_AUTH_TOKEN="sk-your-omniroute-key"
# Gemini CLI reads GOOGLE_GEMINI_BASE_URL at the ROOT (its SDK appends /v1beta/... itself)
export GOOGLE_GEMINI_BASE_URL="http://localhost:20128"
export GEMINI_API_KEY="sk-your-omniroute-key"
```

> ل** الخادم البعيد** استبدل `localhost:20128` بالخادم IP أو المجال، على سبيل المثال `http://<your-server-ip>:20128`.

---

### الخطوة 4 — قم بتكوين كل أداة

#### كود Claude

```bash
# Create ~/.claude/settings.json:
mkdir -p ~/.claude && cat > ~/.claude/settings.json << EOF
{
  "env": {
    "ANTHROPIC_BASE_URL": "http://localhost:20128",
    "ANTHROPIC_AUTH_TOKEN": "sk-your-omniroute-key"
  }
}
EOF
```

استخدم جذر بوابة Anthropic الموحد لرمز Claude. لا تقم بإلحاق `/v1` هنا.

**امتحان:** `claude "say hello"`

---

#### OpenAI Codex

Codex الحديثة (v0.137 +) تقرأ `~/.codex/config.toml` فقط — ينتمي `config.yaml` القديم إلى npm CLI القديم ويتم تجاهله بصمت. يبقى المفتاح API في متغير البيئة `OMNIROUTE_API_KEY` (`env_key`)، وليس داخل الملف أبدًا:

```bash
mkdir -p ~/.codex && cat > ~/.codex/config.toml << EOF
model_provider = "omniroute"

[model_providers.omniroute]
name                 = "OmniRoute"
base_url             = "http://localhost:20128/v1"
env_key              = "OMNIROUTE_API_KEY"
requires_openai_auth = false
EOF
export OMNIROUTE_API_KEY="sk-your-omniroute-key"
```

مرجع كامل (ملفات التعريف، `wire_api`، نوافذ السياق): [CODEX-CLI-CONFIGURATION.md](../guides/CODEX-CLI-CONFIGURATION.md).

**امتحان:** `codex "what is 2+2?"`

---

#### OpenCode

```bash
mkdir -p ~/.config/opencode && cat > ~/.config/opencode/opencode.json << EOF
{
  "\$schema": "https://opencode.ai/config.json",
  "provider": {
    "omniroute": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "OmniRoute",
      "options": {
        "baseURL": "http://localhost:20128/v1",
        "apiKey": "sk-your-omniroute-key"
      },
      "models": {
        "claude-sonnet-4-5": { "name": "claude-sonnet-4-5" },
        "claude-sonnet-4-5-thinking": { "name": "claude-sonnet-4-5-thinking" },
        "gemini-3-flash": { "name": "gemini-3-flash" }
      }
    }
  }
}
EOF
```

**امتحان:** `opencode`

> استخدم `opencode run "your prompt" --model omniroute/claude-sonnet-4-5-thinking --variant high` لإرسال متغيرات التفكير.

---

#### وكيل ترميز باي

قم بتثبيت حزمة Pi Coding Agent الرسمية باستخدام `npm install -g --ignore-scripts @earendil-works/pi-coding-agent`. يقرأ Pi موفري الخدمة المخصصين من `~/.pi/agent/models.json`؛ اضبط `PI_CODING_AGENT_DIR` لنقل دليل الوكيل بالكامل. تتبع لوحة القيادة هذا التجاوز. لا تكتشف Pi نماذج من نقاط النهاية المخصصة، لذلك يكتب OmniRoute النموذج المحدد في `models[]` باستخدام `openai-completions` API الخاص بـ Pi ونقطة النهاية `/v1` المتوافقة مع OmniRoute OpenAI.

في** أدوات CLI → Pi** ، واختر نقطة النهاية، ومفتاح API ، والنموذج، وراجع معاينة الموفر، ثم قم بالتطبيق. المعاينة عبارة عن جزء من الموفر: قم بدمج `providers.omniroute` في `models.json` الموجود لديك عند تكوين Pi يدويًا حتى يظل الموفرون والإعدادات الأخرى سليمة.

```json
{
  "$schema": "https://pi.dev/schemas/models.schema.json",
  "providers": {
    "omniroute": {
      "baseUrl": "http://localhost:20128/v1",
      "api": "openai-completions",
      "apiKey": "sk-your-omniroute-key",
      "omnirouteManaged": true,
      "models": [{ "id": "auto/best-coding", "name": "auto/best-coding" }]
    }
  }
}
```

يقوم Pi بإعادة تحميل `models.json` عند فتح `/model`. اختبر المسار الذي تم تكوينه باستخدام معرف الموفر ومعرف النموذج الذي حددته:

```bash
pi --provider omniroute --model auto/best-coding --print "Reply with a short greeting."
```

المراجع: [نماذج Pi والموفرون المخصصون](https://github.com/earendil-works/pi/blob/main/packages/coding-agent/docs/models.md) ، [ومتغيرات بيئة Pi](https://github.com/earendil-works/pi/blob/main/packages/coding-agent/docs/environment-variables.md) ، [وتعليمات تثبيت Pi](https://github.com/earendil-works/pi/blob/main/packages/coding-agent/README.md).

---

#### Cline (رمز CLI أو VS )

**وضع CLI :**

```bash
mkdir -p ~/.cline/data && cat > ~/.cline/data/globalState.json << EOF
{
  "apiProvider": "openai",
  "openAiBaseUrl": "http://localhost:20128/v1",
  "openAiApiKey": "sk-your-omniroute-key"
}
EOF
```

**وضع كود VS :** إعدادات ملحق Cline → API الموفر: `OpenAI Compatible` → Base URL: `http://localhost:20128/v1`

أو استخدم لوحة القيادة OmniRoute →** أدوات CLI → Cline → تطبيق التكوين** .

---

#### KiloCode (رمز CLI أو VS )

**وضع CLI :**

```bash
kilocode --api-base http://localhost:20128/v1 --api-key sk-your-omniroute-key
```

**إعدادات كود VS :**

```json
{
  "kilo-code.openAiBaseUrl": "http://localhost:20128/v1",
  "kilo-code.apiKey": "sk-your-omniroute-key"
}
```

أو استخدم لوحة القيادة OmniRoute →** أدوات CLI → KiloCode → تطبيق التكوين** .

---

#### متابعة (ملحق كود VS )

تحرير `~/.continue/config.yaml`:

```yaml
models:
  - name: OmniRoute
    provider: openai
    model: auto
    apiBase: http://localhost:20128/v1
    apiKey: sk-your-omniroute-key
    default: true
```

أعد تشغيل VS Code بعد التحرير.

---

#### VS كود المطلعين (`chatLanguageModels.json`)

استخدم هذا عندما يتم تكوين VS Code Insiders لنماذج نقطة النهاية المخصصة وتريد أن يعمل OmniRoute بدون حقل رأس مخصص.

**الموقع الموصى به:**

- Linux: `~/.config/Code - Insiders/User/chatLanguageModels.json`
- Windows: `%APPDATA%/Code - Insiders/User/chatLanguageModels.json`

**مثال باستخدام الاسم المستعار OmniRoute المميز:**

```json
[
  {
    "vendor": "customendpoint",
    "id": "auto",
    "name": "OmniRoute Auto",
    "family": "gpt-4",
    "version": "1.0.0",
    "url": "http://localhost:20128/api/v1/vscode/sk-your-omniroute-key/chat/completions",
    "modelsUrl": "http://localhost:20128/api/v1/vscode/sk-your-omniroute-key/models",
    "requestFormat": "openai-chat-completions",
    "contextWindow": 256000,
    "maxOutputTokens": 32768,
    "auth": {
      "type": "none"
    }
  }
]
```

**ملحوظات:**

- استبدل `sk-your-omniroute-key` بمفتاح API الذي تم إنشاؤه في OmniRoute.
- يجب أن يشير الحقل `url` إلى `/api/v1/vscode/{token}/chat/completions`.
- يجب أن يشير الحقل `modelsUrl` إلى `/api/v1/vscode/{token}/models`.
- تفضل تدفق رأس `/v1` + Bearer العادي عندما يدعم العميل الرؤوس المخصصة.
- تعد الرموز المميزة المضمنة في عنوان URL بمثابة بديل للتوافق وقد تظهر في سجلات المحرر أو سجل الوكيل.

---

#### Kiro CLI (Amazon)

```bash
# Login to your AWS/Kiro account:
kiro-cli login

# The CLI uses its own auth — OmniRoute is not needed as backend for Kiro CLI itself.
# Use kiro-cli alongside OmniRoute for other tools.
kiro-cli status
```

ل**Kiro IDE** تطبيق سطح المكتب، استخدم نقطة النهاية MITM التي تم الكشف عنها بواسطة OmniRoute ضمن `/dashboard/cli-tools → Kiro`.

---

## 10. واجهة سطر الأوامر الداخلية لـ OmniRoute

يوفّر الملف التنفيذي `omniroute` أوامر لإدارة دورة حياة الخادم، والإعداد، والتشخيصات، وإدارة المزوّدين. نقطة الدخول: `bin/omniroute.mjs`.

```bash
omniroute                              # تشغيل الخادم (المنفذ الافتراضي 20128)
omniroute setup                        # معالج إعداد تفاعلي
omniroute doctor                       # فحص الإعدادات وقاعدة البيانات والمنافذ وبيئة التشغيل
omniroute providers list               # اتصالات المزوّدين المُهيأة
omniroute providers test-all           # اختبار كل اتصال نشط
omniroute reset-password               # إعادة تعيين كلمة مرور المسؤول
omniroute logs                         # بث سجلات الطلبات
omniroute health                       # حالة صحية تفصيلية (قواطع الدائرة، وذاكرة التخزين المؤقت، والذاكرة)
omniroute --version                    # طباعة الإصدار
omniroute --help                       # عرض جميع الأوامر
```

### الإعداد والتهيئة

```bash
omniroute setup                        # معالج إعداد تفاعلي
omniroute setup --non-interactive      # وضع CI/الأتمتة (يقرأ متغيرات البيئة والعلامات)
omniroute setup --password '<value>'   # تعيين كلمة مرور المسؤول مباشرةً
omniroute setup --add-provider \
  --provider openai \
  --api-key '<value>' \
  --test-provider                      # إضافة مزوّد واختباره في خطوة واحدة
```

متغيرات البيئة المعروفة للإعداد غير التفاعلي:

| المتغير             | الغرض                                                           |
| ------------------- | --------------------------------------------------------------- |
| `OMNIROUTE_API_KEY` | مفتاح API للمزوّد (مرتبط بـ `--api-key` عبر Commander `.env()`) |
| `DATA_DIR`          | تجاوز دليل بيانات OmniRoute                                     |

تُمرَّر جميع المُدخلات غير التفاعلية الأخرى كعلامات، وليس كمتغيرات بيئة:
`--password`، و`--provider`، و`--provider-name`، و`--provider-base-url`، و`--default-model`
(راجع خيارات `omniroute setup` أعلاه).

### التشخيصات

```bash
omniroute doctor                       # فحص الإعدادات وقاعدة البيانات والمنافذ وبيئة التشغيل والذاكرة وحيوية الخادم
omniroute doctor --json                # JSON قابل للقراءة آليًا
omniroute doctor --no-liveness         # تخطي فحص صحة HTTP
omniroute doctor --host 0.0.0.0        # تجاوز مضيف فحص الحيوية
omniroute doctor --liveness-url <url>  # تجاوز URL الكامل لنقطة نهاية الصحة
```

ينفّذ الأمر doctor الفحوصات التالية: `Config`، و`Database`، و`Storage/encryption`،
و`Port availability`، و`Node runtime`، و`Native binary` ‏(better-sqlite3)،
و`Memory`، و`Server liveness`. وينهي التنفيذ برمز غير صفري إذا كانت نتيجة أي فحص هي `fail`.

### إدارة المزوّدين

```bash
omniroute providers available                       # كتالوج مزوّدي OmniRoute
omniroute providers available --search openai       # تصفية الكتالوج حسب المعرّف/الاسم/الاسم البديل/الفئة
omniroute providers available --category api-key    # التصفية حسب الفئة (api-key، oauth، free، ...)
omniroute providers available --json                # JSON قابل للقراءة آليًا

omniroute providers list                            # اتصالات المزوّدين المُهيأة
omniroute providers list --json

omniroute providers test <id|name>                  # اختبار اتصال مُهيأ واحد
omniroute providers test-all                        # اختبار كل اتصال نشط
omniroute providers validate                        # تحقق بنيوي محلي فقط
omniroute providers add <provider> --credential-env PROVIDER_KEY
omniroute providers import ./providers.json --dry-run --json
omniroute providers auth <provider>                 # تدفق OAuth الحالي
omniroute providers edit <id|name> --default-model <model>
omniroute providers remove <id|name> --yes
```

تعمل أوامر `providers add/import/auth/edit/remove` وفق نهج API أولًا، ولذلك تعمل مع
السياق المحلي أو البعيد النشط. ينبغي إدخال بيانات الاعتماد باستخدام
`--credential-stdin` أو `--credential-env`؛ ويعرض `--dry-run --json` فقط
معلومات الوجود/البنية المنقّحة. يقرأ `providers available` كتالوج OmniRoute؛
وتحتفظ أوامر `providers list/test/test-all/validate` بسلوك SQLite المحلي الخاص بها،
ولا تتطلب تشغيل الخادم.

بالنسبة إلى عقدة مخصّصة متوافقة مع OpenAI أو Anthropic، اربط بيانات الاعتماد
بمعرّف العقدة الذي يعيده `omniroute nodes add`، باستخدام `omniroute keys add "$NODE_ID" --stdin`.
يتطلب ذلك خادمًا قيد التشغيل ومصادقة إدارية للسياق النشط.
تستخدم واجهة سطر الأوامر `POST /api/providers`، التي تتحقق من صحة العقدة وتنسخ إعدادات
نقطة نهايتها إلى الاتصال. يؤدي عدم وجود العقدة، أو فشل التفويض، أو عدم توفر
الخادم إلى إرجاع خطأ من دون إنشاء بيانات اعتماد احتياطية محلية.

يعيّن `nodes add --base-url` نقطة نهاية العقدة؛ وهي تختلف عن عنوان الخادم
في `OMNIROUTE_BASE_URL`. بالنسبة إلى ملفات OpenAPI، استخدم
`omniroute openapi dump --format json --out ./openapi.json`؛ ويحدد الخيار العام `--output`
تنسيق عرض واجهة سطر الأوامر، وليس اسم ملف الوجهة.

### الاسترداد وإعادة التعيين

```bash
omniroute reset-password                # إعادة تعيين كلمة مرور المسؤول (أيضًا: omniroute-reset-password)
omniroute reset-encrypted-columns       # عرض تحذير + تشغيل تجريبي لإعادة تعيين بيانات الاعتماد المشفرة
omniroute reset-encrypted-columns --force  # تصفير بيانات الاعتماد المشفرة فعليًا في SQLite
```

### تصدير بيانات الاعتماد (⚠ تعامل معها بحذر)

```bash
omniroute auth export                                 # عرض تحذير + طلب تأكيد — دون الوصول إلى قاعدة البيانات
omniroute auth export --force                          # تصدير بيانات الاعتماد المفكوكة التشفير لجميع الاتصالات إلى stdout بصيغة JSON
omniroute auth export --force --id <id>                 # تصدير الاتصال المطابق فقط
omniroute auth export --force --format env               # إخراج أسطر OMNIROUTE_<PROVIDER>_<FIELD>=<value>
omniroute auth export --force --out creds.json           # الكتابة إلى ملف (يُنشأ بأذونات 0600)
```

`auth export` يعمل **محليًا فقط** (قراءة مباشرة من SQLite، دون مسار HTTP)، ويطبع/يكتب عمدًا
قيم `apiKey`/`accessToken`/`refreshToken`/`idToken` **بنص صريح** — وهذه ميزة وليست
خطأً. لا تتم قراءة أي شيء من قاعدة البيانات، ولا يُفك تشفير أي شيء، دون `--force`. يظهر دائمًا
شريط تحذير على stderr قبل إخراج أي نص صريح. يتطلب تعيين `STORAGE_ENCRYPTION_KEY`.
يتم الإبلاغ عن الحقل الذي يفشل فك تشفيره (مفتاح قديم، أو نص مُشفّر تالف) بصيغة
`<field>DecryptFailed: true` بدلًا من إيقاف عملية التصدير بأكملها أو كشف الخطأ الأساسي.

### الأوامر الفرعية الأخرى

تفترض هذه الأوامر وجود خادم OmniRoute قيد التشغيل، ما لم يُذكر خلاف ذلك:

```bash
omniroute status                       # حالة شاملة لوقت التشغيل
omniroute logs                         # بث سجلات الطلبات (--json، --search، --follow)
omniroute config list                  # عرض أدوات CLI المُهيأة

omniroute provider list                # سرد المزوّدين المتاحين (اسم مستعار للأمر providers list)
omniroute provider add                 # تسجيل OmniRoute كمزوّد في أداة
omniroute keys add | list | remove     # إدارة مفاتيح API
omniroute models [provider]            # سرد النماذج (--json، --search)
omniroute combo list | switch | create | delete

omniroute backup                       # أخذ لقطة للإعدادات + قاعدة البيانات
omniroute restore                      # الاستعادة من لقطة سابقة

omniroute health                       # حالة صحية مفصّلة (قواطع الدائرة، ذاكرة التخزين المؤقت، الذاكرة)
omniroute quota                        # استخدام حصة المزوّد
omniroute cache                        # حالة ذاكرة التخزين المؤقت
omniroute cache clear                  # مسح ذاكرات التخزين المؤقت الدلالية والخاصة بالتوقيعات

omniroute mcp status | restart         # حالة خادم MCP / إعادة تشغيله
omniroute a2a status | card            # حالة خادم A2A / بطاقة الوكيل

omniroute tunnel list | create | stop  # إدارة الأنفاق (cloudflare/tailscale/ngrok)
omniroute env show | get <k> | set <k> <v>  # فحص / تعيين متغيرات البيئة (مؤقتًا)

omniroute test                         # اختبار أولي لاتصال المزوّد
omniroute update                       # التحقق من وجود تحديثات
omniroute completion                   # إنشاء الإكمال التلقائي للصدفة
```

### الخيارات الشائعة

| الخيار              | الوصف                                                    |
| ------------------- | -------------------------------------------------------- |
| `--no-open`         | عدم فتح المتصفح تلقائيًا عند بدء التشغيل                 |
| `--port <n>`        | تجاوز منفذ API (الافتراضي 20128)                         |
| `--mcp`             | التشغيل كخادم MCP عبر stdio (لبيئات IDE)                 |
| `--non-interactive` | وضع CI (دون مطالبات؛ يقرأ من البيئة/الخيارات)            |
| `--json`            | مخرجات JSON قابلة للقراءة آليًا (doctor، providers، إلخ) |
| `--help`, `-h`      | عرض المساعدة الخاصة بالأمر                               |
| `--version`, `-v`   | طباعة الإصدار المُثبّت                                   |

---

## نقاط نهاية API المتاحة

| نقطة النهاية               | الوصف                               | الاستخدام                             |
| -------------------------- | ----------------------------------- | ------------------------------------- |
| `/v1/chat/completions`     | الدردشة القياسية (جميع المزوّدين)   | جميع الأدوات الحديثة                  |
| `/v1/responses`            | واجهة Responses API (بتنسيق OpenAI) | Codex، وسير عمل الوكلاء               |
| `/v1/completions`          | إكمالات النص القديمة                | الأدوات القديمة التي تستخدم `prompt:` |
| `/v1/embeddings`           | تضمينات النص                        | RAG، والبحث                           |
| `/v1/images/generations`   | توليد الصور                         | GPT-Image، وFlux، وغيرها              |
| `/v1/audio/speech`         | تحويل النص إلى كلام                 | ElevenLabs، وOpenAI TTS               |
| `/v1/audio/transcriptions` | تحويل الكلام إلى نص                 | Deepgram، وAssemblyAI                 |

أمثلة جاهزة للصق باستخدام عنوان URL مرمّز لـ OmniRoute:

```txt
مثال على الرمز: sk-a3ab3c080beaee3a-69f4a4-070d71af

عنوان OpenAI الأساسي القياسي: http://localhost:20128/v1
نماذج VS Code: http://localhost:20128/api/v1/vscode/sk-a3ab3c080beaee3a-69f4a4-070d71af/models
دردشة VS Code: http://localhost:20128/api/v1/vscode/sk-a3ab3c080beaee3a-69f4a4-070d71af/chat/completions
استجابات VS Code: http://localhost:20128/api/v1/vscode/sk-a3ab3c080beaee3a-69f4a4-070d71af/responses
وسوم Ollama: http://localhost:20128/api/v1/vscode/sk-a3ab3c080beaee3a-69f4a4-070d71af/api/tags
دردشة Ollama: http://localhost:20128/api/v1/vscode/sk-a3ab3c080beaee3a-69f4a4-070d71af/api/chat
```

---

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

| الخطأ                                          | السبب                            | الحل                                                    |
| ---------------------------------------------- | -------------------------------- | ------------------------------------------------------- |
| `Connection refused`                           | OmniRoute غير مشغّل              | `omniroute serve`                                       |
| `401 Unauthorized`                             | مفتاح API غير صحيح               | تحقّق في `/dashboard/api-manager`                       |
| `No combo configured`                          | لا توجد تركيبة توجيه نشطة        | قم بإعدادها في `/dashboard/combos`                      |
| تعرض CLI الرسالة "not installed"               | الملف التنفيذي غير موجود في PATH | تحقّق باستخدام `which <command>`                        |
| تعرض لوحة المعلومات "not detected" بعد التثبيت | ذاكرة التخزين المؤقت قديمة       | انقر فوق "⟳ تحديث الاكتشاف" في لوحة المعلومات           |
| الرابط القديم `/dashboard/cli-tools`           | إشارة مرجعية لما قبل v3.8.6      | يُعاد توجيهه تلقائيًا إلى `/dashboard/cli-code` (308)   |
| الرابط القديم `/dashboard/agents`              | إشارة مرجعية لما قبل v3.8.6      | يُعاد توجيهه تلقائيًا إلى `/dashboard/acp-agents` (308) |

## إدارة سياسة مفتاح الاستدلال باستخدام OmniRoute CLI

استخدم سياق إدارة موثّقًا (راجع [الوضع البعيد](../guides/REMOTE-MODE.md))
لفحص مفتاح استدلال موجود أو تحديثه باستخدام معرّفه:

```bash
omniroute --output json keys policy show KEY_ID
omniroute keys policy set KEY_ID --unrestricted
omniroute --output json keys policy show KEY_ID
```

يمثل `--unrestricted` اسمًا بديلًا لـ `--model-access-mode all`. يؤدي التحديث إلى مسح
قائمة النماذج المسموح بها. ويحافظ على النطاقات وقواعد الاتصال والنماذج المحظورة وحدود المعدل
وحدود التكلفة، ولذلك لا يزال بإمكان عناصر التحكم الأخرى هذه رفض الطلب. يؤدي تحديد
`--allowed-models ""` صراحةً أيضًا إلى اختيار `all`؛ ادمجه مع
`--model-access-mode restricted` للإبقاء على مفتاح مقيّد من دون نماذج مسموح بها.
تؤدي قائمة غير فارغة مفصولة بفواصل إلى اختيار `restricted` ما لم يُحدَّد خلاف ذلك صراحةً.
يُرفض الجمع المتعارض بين `all` وقائمة سماح غير فارغة قبل إرسال الطلب.

يضبط `--rate-limit 30` عدد الطلبات في الدقيقة ويحافظ على قواعد الفترات الزمنية
الأخرى. يفعّل `--max-cost 5` الحد اليومي بالدولار الأمريكي من دون تغيير الحد الأسبوعي؛
ويزيل `--max-cost 0` الحد اليومي مع الحفاظ على مفتاح تبديل حد الاستخدام الحالي
والحد الأسبوعي. تظل حقول السياسة المحذوفة دون تغيير. تقرأ تغييرات المعدل
السياسة الحالية أولًا؛ تجنّب إجراء تعديلات متزامنة على مصفوفة حدود المعدل للمفتاح نفسه.

تستخدم أوامر السياسة الطلبين الموثّقين `GET`/`PATCH /api/keys/{id}` وتلتزم بالسياق النشط
وخيار `--api-key` العام. يحتوي إخراج JSON على حقول السياسة فقط،
من دون المفتاح المخزّن أو تمثيله المحجوب. لا يمكن لبيانات اعتماد مخصّصة للاستدلال فقط
تخويل تغييرات الإدارة. تتطلب استجابة 401/403 التحقق من بيانات اعتماد الإدارة
والسياق؛ وهي لا تثبت وجود فشل في رمز CLI المحلي أو قيمة salt.
راجع [رمز CLI](../security/CLI_TOKEN.md) للاطلاع على عقد المصادقة المحلية المنفصل.