لعملاء الذكاء الاصطناعي: تعليمات الإعداد خطوة بخطوة — /docs/agents.md، فهرس الوثائق — /llms.txt.

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

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

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

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

الموجّه للوكيل

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

أدناه الدليل نفسه. يستلمه الوكيل بصيغة Markdown على العنوان /docs/agents.md.

القواعد#

مفتاح API ينشئه إنسان — في لوحة الحساب على gate.joingonka.ai. لا تُنشئ حسابًا ولا مفاتيح بنفسك: اطلب المفتاح من المستخدم.
احفظ المفتاح في متغير البيئة 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	`cursor`
Claude Code	`claude-code`
OpenClaw	`openclaw`
OpenCode	`opencode`
Continue	`continue`
Cline	`cline`
Aider	`aider`
LangChain	—
n8n	—
Open WebUI	—
LibreChat	—
Hermes	`hermes`
Kilo Code	`kilo`
Roo Code	`roo`
LlamaIndex	—
PydanticAI	—
Vercel AI SDK	—
TanStack AI	—
ZCode	`zcode`
JetBrains	`jetbrains`
Copilot BYOK	`copilot-byok`
Zed	`zed`
Pi	`pi`
Codex CLI	`codex`
DeepSeek Harness	—
MiniMax Code	`minimax-code`
Warp	—
Trae	—
Cherry Studio	—
omp (Oh My Pi)	`omp`
OpenHands	—
Qwen Code	`qwen-code`
Goose	`goose`
Crush	`crush`
Zoo Code	`zoo`
Kimi Code	`kimi-code`
Factory Droid	`droid`
MiMo Code	`mimo-code`

التحقق#

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

cURL

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

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

cURL

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`	خلل من جهة البوابة أو الشبكة — لا علاقة للمفتاح بالأمر. أعد المحاولة لاحقًا؛ وحالة الشبكة على صفحة حالة الشبكة.

كل رموز الردود والحدود — في قسم الأخطاء والحدود.

التقرير#

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

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

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

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

العنوان	المحتوى
/llms.txt	فهرس الوثائق لنماذج اللغة.
/llms-full.txt	كل الوثائق في ملف واحد.
`/docs/<page>.md`	نسخة Markdown من صفحة الوثائق: العنوان نفسه مع `.md` في النهاية (/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

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

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

// 02القواعد#

// 03حقائق#

// 04الإعداد#