> لعملاء الذكاء الاصطناعي: تعليمات الإعداد خطوة بخطوة — [`/docs/agents.md`](https://gate.joingonka.ai/docs/agents.md)، فهرس الوثائق — [`/llms.txt`](https://gate.joingonka.ai/llms.txt).

# لوكلاء الذكاء الاصطناعي

كيفية تكليف وكيل ذكاء اصطناعي بعملية الربط: طلب جاهز لأي أداة. أدناه — عناوين التوثيق القابلة للقراءة آليًا ومهارة يثبّتها الوكيل بأمر واحد.

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

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

```text
اربط أداتك بـ JoinGonka Gateway — واجهة API المتوافقة مع OpenAI وAnthropic لشبكة Gonka — حسب التعليمات في https://gate.joingonka.ai/docs/agents.md. سأزوّدك بالمفتاح بنفسي: لا تحفظه في ملفات المستودع ولا تغيّر متغيرات البيئة العامة. في النهاية، تحقق من الاتصال بطلب قصير وأبلغني بالنتيجة.
```

أدناه الدليل نفسه. يستلمه الوكيل بصيغة Markdown على العنوان [/docs/agents.md](https://gate.joingonka.ai/docs/agents.md).

## القواعد

- مفتاح API ينشئه إنسان — في لوحة الحساب على [gate.joingonka.ai](https://gate.joingonka.ai/keys). لا تُنشئ حسابًا ولا مفاتيح بنفسك: اطلب المفتاح من المستخدم.
- احفظ المفتاح في متغير البيئة `JOINGONKA_API_KEY` في جلسة الطرفية. لا تكتبه في ملفات خاضعة لـ git، ولا تُدوّره، ولا تُخرجه في التقرير.
- لا تُغيّر المتغيرات العامة `OPENAI_*` و`ANTHROPIC_*` — لا في ملف تعريف الصدفة ولا في النظام: أدوات المستخدم الأخرى تقرؤها. المفتاح والعنوان يُكتبان في إعدادات الأداة نفسها — هكذا يفعل المُثبِّت.

## حقائق

- العنوان الأساسي لعملاء OpenAI API: `https://gate.joingonka.ai/v1`
- العنوان الأساسي لعملاء Anthropic API، بدون `/v1`: `https://gate.joingonka.ai`
- يُمرَّر المفتاح في الترويسة `Authorization: Bearer jg-…` أو `x-api-key: jg-…`
- المفتاح الخاص بطلبات الموديلات يبدأ بـ `jg-`؛ ومفتاح الإدارة `gm-` لا يمنح الوصول إلى الموديلات.
- النموذج المُوصى به: `MiniMaxAI/MiniMax-M2.7`
- قائمة النماذج المتاحة: `GET https://gate.joingonka.ai/v1/models`
- لكل مفتاح — حتى 120 طلبًا في الدقيقة، وعند تجاوز الحد يأتي رد 429 مع الترويسة `Retry-After`. الحدود والمُهَل — في رد `GET /v1/capabilities`، الحقل `limits`.

## الإعداد

ابحث عن أداة المستخدم في الجدول في نهاية القسم. إن وُجدت قيمة `--tool` — أعدّها بالمُثبِّت، وإن لم توجد — يدويًا وفق الدليل.

### عبر المُثبِّت

أمر واحد بلا أسئلة: المفتاح — من متغير البيئة، والموديل — عبر علم. سيكتب المُثبِّت إعدادات الأداة، ويحفظ نسخة من الإعدادات السابقة، ويتحقق من الاتصال بطلب إلى البوابة.

```bash
JOINGONKA_API_KEY=<key> npx -y @joingonka/setup --tool <id> --model MiniMaxAI/MiniMax-M2.7 --non-interactive
```

| العلم | ماذا يفعل |
| --- | --- |
| `--tool <id>` | أي أداة تُضبط — القيمة من جدول الأدوات. |
| `--model <id>` | معرّف الموديل: الموصى به — `MiniMaxAI/MiniMax-M2.7`، وكل المتاح — `GET /v1/models`. |
| `--non-interactive` | بلا أسئلة: المفتاح يُؤخذ من `JOINGONKA_API_KEY`. |
| `--scope local` | الإعدادات في المشروع الحالي، لا في المجلد الرئيسي. لـ Claude Code فقط؛ ويُضاف ملف الإعدادات إلى `.gitignore`. |
| `--no-verify` | لا تتحقق من الاتصال بعد كتابة الإعدادات. |

| رمز الخروج | ماذا يعني |
| --- | --- |
| `0` | تم: كُتبت الإعدادات ونجح طلب التحقق. وإذا تعذّر التحقق بسبب الشبكة أو الرصيد، يطبع المُثبِّت تحذيرًا لكنه يخرج أيضًا بالرمز 0 — أبلغ المستخدم بذلك. |
| `1` | فشل الإعداد، والسبب في المخرجات: مثلًا قيمة `--tool` غير معروفة، أو `JOINGONKA_API_KEY` غير محدّد، أو المفتاح لا يبدأ بـ `jg-`. |
| `2` | كُتبت الإعدادات لكن طلب التحقق لم ينجح: تحقق من المفتاح ومعرّف الموديل. |

إذا كانت الأداة قيد التشغيل، أعد تشغيلها: الإعدادات تُقرأ عند بدء التشغيل.

### يدويًا

للأداة التي لا مُثبِّت لها، افتح دليلها (الرابط في الجدول أدناه) واضبط ثلاث قيم:

- العنوان الأساسي — `https://gate.joingonka.ai/v1` لعملاء OpenAI API أو `https://gate.joingonka.ai` لعملاء Anthropic API؛
- المفتاح — في حقل مفتاح API في إعدادات الأداة؛
- الموديل — `MiniMaxAI/MiniMax-M2.7` أو غيره من `GET /v1/models`.

### الأدوات والأدلة

| الأداة | `--tool` |
| --- | --- |
| [Cursor](https://joingonka.ai/ar/knowledge/cursor/) | `cursor` |
| [Claude Code](https://joingonka.ai/ar/knowledge/claude-code/) | `claude-code` |
| [OpenClaw](https://joingonka.ai/ar/knowledge/openclaw/) | `openclaw` |
| [OpenCode](https://joingonka.ai/ar/knowledge/opencode/) | `opencode` |
| [Continue](https://joingonka.ai/ar/knowledge/continue-dev/) | `continue` |
| [Cline](https://joingonka.ai/ar/knowledge/cline/) | `cline` |
| [Aider](https://joingonka.ai/ar/knowledge/aider/) | `aider` |
| [LangChain](https://joingonka.ai/ar/knowledge/langchain/) | — |
| [n8n](https://joingonka.ai/ar/knowledge/n8n/) | — |
| [Open WebUI](https://joingonka.ai/ar/knowledge/open-webui/) | — |
| [LibreChat](https://joingonka.ai/ar/knowledge/librechat/) | — |
| [Hermes](https://joingonka.ai/ar/knowledge/hermes/) | `hermes` |
| [Kilo Code](https://joingonka.ai/ar/knowledge/kilo-code/) | `kilo` |
| [Roo Code](https://joingonka.ai/ar/knowledge/roo-code/) | `roo` |
| [LlamaIndex](https://joingonka.ai/ar/knowledge/llamaindex/) | — |
| [PydanticAI](https://joingonka.ai/ar/knowledge/pydantic-ai/) | — |
| [Vercel AI SDK](https://joingonka.ai/ar/knowledge/vercel-ai-sdk/) | — |
| [TanStack AI](https://joingonka.ai/ar/knowledge/tanstack-ai/) | — |
| [ZCode](https://joingonka.ai/ar/knowledge/zcode/) | `zcode` |
| [JetBrains](https://joingonka.ai/ar/knowledge/jetbrains/) | `jetbrains` |
| [Copilot BYOK](https://joingonka.ai/ar/knowledge/copilot-byok/) | `copilot-byok` |
| [Zed](https://joingonka.ai/ar/knowledge/zed/) | `zed` |
| [Pi](https://joingonka.ai/ar/knowledge/pi/) | `pi` |
| [Codex CLI](https://joingonka.ai/ar/knowledge/codex/) | `codex` |
| [DeepSeek Harness](https://joingonka.ai/ar/knowledge/deepseek-harness/) | — |
| [MiniMax Code](https://joingonka.ai/ar/knowledge/minimax-code/) | `minimax-code` |
| [Warp](https://joingonka.ai/ar/knowledge/warp/) | — |
| [Trae](https://joingonka.ai/ar/knowledge/trae/) | — |
| [Cherry Studio](https://joingonka.ai/ar/knowledge/cherry-studio/) | — |
| [omp (Oh My Pi)](https://joingonka.ai/ar/knowledge/omp/) | `omp` |
| [OpenHands](https://joingonka.ai/ar/knowledge/openhands/) | — |
| [Qwen Code](https://joingonka.ai/ar/knowledge/qwen-code/) | `qwen-code` |
| [Goose](https://joingonka.ai/ar/knowledge/goose/) | `goose` |
| [Crush](https://joingonka.ai/ar/knowledge/crush/) | `crush` |
| [Zoo Code](https://joingonka.ai/ar/knowledge/zoo-code/) | `zoo` |
| [Kimi Code](https://joingonka.ai/ar/knowledge/kimi-code/) | `kimi-code` |
| [Factory Droid](https://joingonka.ai/ar/knowledge/factory-droid/) | `droid` |
| [MiMo Code](https://joingonka.ai/ar/knowledge/mimo-code/) | `mimo-code` |

## التحقق

التحقق من المفتاح — طلب الرصيد: لا يستهلك رموزًا، والمفتاح يُؤخذ من `JOINGONKA_API_KEY`:

```bash
curl -s https://gate.joingonka.ai/api/balance \
  -H "Authorization: Bearer $JOINGONKA_API_KEY"
```

التحقق من العنوان والمفتاح والموديل — طلب قصير إلى الموديل:

```bash
curl -s https://gate.joingonka.ai/v1/chat/completions \
  -H "Authorization: Bearer $JOINGONKA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "MiniMaxAI/MiniMax-M2.7", "messages": [{"role": "user", "content": "Say OK"}], "max_tokens": 32}'
```

رد `200` مع نص الموديل — الاتصال يعمل. يقوم المُثبِّت بهذا التحقق بنفسه: وبعده يكفي رمز الخروج 0.

## إذا حدث خطأ ما

يأتي الخطأ في الحقل `error` في متن الرد — مع النوع ونص السبب.

| الرد | ما العمل |
| --- | --- |
| `401 authentication_error` | لم يُقبل المفتاح. تحقق من أنه منسوخ بالكامل ومُمرَّر في `Authorization: Bearer` أو `x-api-key`؛ والمفتاح الجديد ينشئه المستخدم. |
| `402 insufficient_funds` | لا توجد أموال في الرصيد. أبلغ المستخدم: يُشحن الرصيد في لوحة الحساب. |
| `402 child_key_limit_exceeded` | استُهلك حد المفتاح الفرعي. يلزم مفتاح آخر أو حد أكبر — وهذا قرار صاحب المفتاح. |
| `403 forbidden` | هذا مفتاح الإدارة `gm-`: لا يمنح الوصول إلى الموديلات. يلزم مفتاح `jg-`. |
| `400 invalid_request_error` | خطأ في الطلب. إذا لم يُعثر على الموديل، ففي نص الخطأ قائمة بالمعرّفات المتاحة — خذ منها أو من `GET /v1/models`. |
| `404 model_not_found` | هذا الموديل غير متاح الآن — اختر آخر من `GET /v1/models`. |
| `429` | طلبات كثيرة جدًا أو الشبكة مشغولة. انتظر عدد الثواني المذكور في الترويسة `Retry-After` ثم أعد المحاولة. |
| `503 model_unavailable` | الشبكة لا تخدم الموديل الآن. انتقل إلى الموديل المذكور في نص الخطأ أو إلى آخر من `GET /v1/models`. |
| `504 upstream_timeout` | لم تبدأ الشبكة بالرد في الوقت المناسب. أعد الطلب؛ وللردود الطويلة فعّل `stream: true`. |
| `502` | خلل من جهة البوابة أو الشبكة — لا علاقة للمفتاح بالأمر. أعد المحاولة لاحقًا؛ وحالة الشبكة على صفحة [حالة الشبكة](https://gate.joingonka.ai/ar/status). |

كل رموز الردود والحدود — في قسم [الأخطاء والحدود](https://gate.joingonka.ai/ar/docs/errors).

## التقرير

في النهاية أبلغ المستخدم:

- أي أداة ضُبطت وأي ملف إعدادات كُتب (المسار يطبعه المُثبِّت، والنسخة السابقة بجانبه)؛
- العنوان الأساسي ومعرّف النموذج؛
- نتيجة الفحص: رمز الاستجابة وردّ النموذج — أو سبب تعذّر الفحص؛
- ما يبقى على المستخدم فعله بنفسه: مثل إعادة تشغيل الأداة أو تعبئة الرصيد.

لا تُدرج المفتاح في التقرير.

## عناوين موجّهة للآلات

| العنوان | المحتوى |
| --- | --- |
| [/llms.txt](https://gate.joingonka.ai/llms.txt) | فهرس الوثائق لنماذج اللغة. |
| [/llms-full.txt](https://gate.joingonka.ai/llms-full.txt) | كل الوثائق في ملف واحد. |
| `/docs/<page>.md` | نسخة Markdown من صفحة الوثائق: العنوان نفسه مع `.md` في النهاية ([/docs/models.md](https://gate.joingonka.ai/docs/models.md)) أو طلب الصفحة مع ترويسة `Accept: text/markdown`. |
| `GET /v1/capabilities` | قدرات البوابة وحدودها — حقل `limits`. |
| `GET /v1/models` | النماذج المتاحة حالياً. |
| `GET /api/pricing` | الأسعار لكل نموذج لكل مليون رمز والعمولات. |
| `GET /v1/network-status` | حالة النماذج والحوادث. |

## مهارة للوكيل

يمكن تثبيت الإرشادات كمهارة (skill) للوكيل — فتكون دائماً في متناوله ودون الحاجة إلى prompt:

```bash
npx skills add https://gate.joingonka.ai
```