OpenHands + JoinGonka Gateway: وكيل على نقطة النهاية الخاصة بك

يحتوي المشروع اليوم على عدة واجهات، ويعتمد مكان العثور على إعدادات النموذج على الواجهة التي تشغلها. القيم نفسها في كل مكان — يختلف فقط المسار للوصول إليها.

بالنسبة لـ Agent Canvas، تحتاج إلى Node.js و uv — حيث يعمل عليه الخادم المحلي للوكيل (التفاصيل في دليل التثبيت). تشير التعليمات إلى Node.js 22.12 أو أحدث، ولكن الحزمة بدءاً من الإصدار 1.17 تتطلب Node.js 24 أو أحدث — قم بتثبيت إصدار 24 لتجنب تحذيرات الإصدار غير المتوافق. يوجد أيضاً خيار داخل حاوية: صورة ghcr.io/openhands/agent-canvas توفر الواجهة على http://localhost:8000/canvas ولا ترى سوى المجلدات التي قمت بتثبيتها (mount).

مفتاح JoinGonka. سجل في gate.joingonka.ai/register، وأكد العنوان وأنشئ مفتاحاً ببادئة jg- في قسم "مفاتيح API". مفتاح واحد ورصيد واحد صالحان لجميع نماذج الشبكة. لا يوجد OpenHands في قائمة أدوات المثبت @joingonka/setup، وهذا ليس تقصيراً: إعداداته موجودة في الواجهة وفي التخزين الآمن للخلفية (backend)، وليس في ملف تكوين نصي يمكن تعديله يدوياً من الخارج.

الخطوة 1. قم بتشغيل Agent Canvas وافتح Settings > LLM. يقترح معالج الإعداد الأولي مزود OpenHands الافتراضي — يمكنك تخطي هذه الخطوة، فمن السهل العودة إلى الإعدادات لاحقاً.

الخطوة 2. اضغط على Add LLM Profile وانتقل إلى علامة التبويب Advanced: علامة التبويب Basic توفر فقط المزودين والنماذج من القائمة المدمجة.

الخطوة 3. املأ الحقول الثلاثة التالية:

الخطوة 4. احفظ الملف الشخصي. قبل الحفظ، يقوم Canvas بالتحقق من الإعداد عبر طلب من الواجهة الخلفية (backend): إذا تم رفض المفتاح أو كان النموذج غير متاح، فلن يتم حفظ الملف الشخصي وستظهر لك رسالة خطأ.

الخطوة 5. ابدأ محادثة جديدة وأرسل رسالة قصيرة. المحادثات المفتوحة مسبقاً تستمر في العمل على النموذج الذي بدأت به.

لماذا openai/. يقوم LiteLLM بتحديد المزود بناءً على بادئة النموذج. البادئة openai/ لا تعني «نموذج من OpenAI»، بل تعني «التواصل مع الخادم باستخدام بروتوكول OpenAI Chat Completions». يتم قص الجزء الأول فقط، لذا يصل المعرف الحقيقي — deepseek-ai/DeepSeek-V4-Flash-0731 — إلى البوابة. في وثائق OpenHands، يتم عرض نفس المخطط بمثال openai/qwen/qwen3.6-35b-a3b. بدون البادئة، سيرفض LiteLLM العمل مع ظهور رسالة LLM Provider NOT provided.

لماذا /v1 ولا شيء آخر. يتصل LiteLLM بالخادم عبر عميل OpenAI الرسمي، وهو الذي يقوم تلقائياً بإضافة /chat/completions. لذا يجب أن ينتهي العنوان بـ /v1: بدون اللاحقة، سيضيع الطلب بعيداً عن واجهة برمجة التطبيقات (API)، ومع إضافة زائدة، سيذهب إلى مسار غير موجود. ومتطلب آخر لـ Canvas: يجب أن يكون العنوان متاحاً من الواجهة الخلفية وليس فقط من المتصفح. البوابة عبارة عن عنوان HTTPS عام، ومن حاوية Docker يمكن رؤيتها كما تُرى من المضيف؛ الحيل مثل host.docker.internal مطلوبة فقط للنماذج الموجودة على جهازك.

ملفات تعريف للنماذج الثلاثة. قم بإنشاء ملف تعريف لكل نموذج في الشبكة وسمِّها بأسماء قصيرة — مثل deepseek، glm، وminimax (تشير الوثائق إلى حد أقصى قدره عشرة ملفات تعريف). يمكنك التبديل مباشرة أثناء المحادثة دون فقدان السياق: عن طريق زر اختيار الملف الشخصي في حقل الإدخال أو بواسطة الأمر /model glm؛ الأمر /model بدون وسيطة سيعرض قائمة. لكي لا تضطر لإدخال المفتاح في كل ملف تعريف، يمكنك حفظه مرة واحدة في قسم Provider Connections — وهو متاح في الواجهة الخلفية المحلية.

الواجهة القديمة في Docker. الحقول هي نفسها: Settings → علامة التبويب LLM → تفعيل Advanced → Custom Model، Base URL، API Key → Save Changes.

يُثبَّت CLI بأمر واحد عبر uv، وعند أول تشغيل يمرّرك بنفسه عبر إعداد النموذج؛ وبعدها تعود إليه بـCtrl+P → Settings:

uv tool install openhands --python 3.12
openhands

مع السكربتات تكون متغيرات البيئة أسهل. وهنا تفصيل مهم: CLI يتجاهلها افتراضيًا ولا يطبّقها إلا مع الخيار --override-with-envs — لتشغيل واحد، دون حفظ أي شيء:

export LLM_MODEL="openai/deepseek-ai/DeepSeek-V4-Flash-0731"
export LLM_BASE_URL="https://gate.joingonka.ai/v1"
export LLM_API_KEY="jg-your-key"

openhands --override-with-envs

المجموعة نفسها تعمل بلا واجهة — لأجل CI والمهام الدفعية:

openhands --headless --override-with-envs -t "Read calc.py and tell me in one sentence whether it has a bug."

في وضع headless يعمل الوكيل دائمًا بالموافقة التلقائية، فشغّله حيث يُسمح له بكل شيء: في مجلد منفصل أو حاوية. والخيار --json يحوّل المخرجات إلى تدفّق أحداث JSONL — مريح للتحليل داخل خطّ أنابيب. وبهذه الطريقة بالضبط اختبرنا الربط في 21 سبتمبر 2026 على CLI 1.16.0: في الترويسة يطبع CLI العبارة Agent initialized with model: openai/deepseek-ai/DeepSeek-V4-Flash-0731، ثم يقرأ الوكيل الملف ويجيب في صلب الموضوع.

إعدادات CLI المحفوظة تقع في ~/.openhands/agent_settings.json: يتغيّر النموذج فيها بتعديل ثلاثة حقول في كتلة llm — model وapi_key وbase_url. ولا يُنصح بإنشاء الملف من الصفر: فمعالج التشغيل الأول يكتب فيه بقية إعدادات الوكيل، ومنها ضغط السجل، وبدونه تصطدم المحادثة الطويلة بنافذة السياق.

وإذا كنت تدمج الوكيل في كودك الخاص، فإن OpenHands SDK يستقبل القيم الثلاث نفسها:

from pydantic import SecretStr
from openhands.sdk import LLM

llm = LLM(
    model="openai/deepseek-ai/DeepSeek-V4-Flash-0731",
    base_url="https://gate.joingonka.ai/v1",
    api_key=SecretStr("jg-your-key"),
)

سعر النماذج على الشبكة واحد، لذا الاختيار يعتمد على السلوك. بالنسبة للوكيل المستقل (Autonomous Agent)، هناك رقمان مهمان. نافذة السياق (Context window): كل خطوة تعيد إرسال السجل، وكلما كانت النافذة أطول، زادت مدة عمل الوكيل دون فقدان البيانات. سقف الاستجابة (Response limit): الخطوة التي يكتب فيها الوكيل ملفاً كبيراً بالكامل يجب أن تتسع في استجابة واحدة. في الجدول - نتائج اختبارنا لنفس المهمة (قراءة ملف والعثور على خطأ) عبر OpenHands CLI 1.16.0 مع SDK 1.21.0.

تعمل خطة العمل للمهام الطويلة وفقاً لنصيحة وثائق OpenHands - خطط بنموذج ونفذ بآخر. ابدأ المحادثة بملف تعريف glm واطلب خطة دون تعديل الملفات؛ ثم أرسل /model deepseek وأعطِ أمر التنفيذ. يتم حفظ السجل والملفات وحالة المهمة عند التبديل. اجعل ملف تعريف minimax خياراً ثالثاً: من السهل الانتقال إليه عندما تنفد سعة النموذجين الآخرين في ساعة الذروة، ويمكن استخدامه أيضاً في Settings > Application لتوليد عناوين المحادثات.

ضغط السجل. حتى النافذة التي تتسع لمئات الآلاف من الرموز (tokens) محدودة في المهمة التي تستغرق ساعات طويلة. في OpenHands، المسؤول عن ذلك هو المكثف (condenser): فهو يختصر الأحداث القديمة في ملخص موجز، مما يقلل التأخير واستهلاك الرموز في المحادثات الطويلة وفقاً للوثائق. في Agent Canvas، يتم إعداده في قسم Settings > Condenser؛ وفي اختبارنا، قام CLI بتفعيله تلقائياً بحد 80 حدثاً.

حدود النموذج. يأخذ OpenHands نافذة السياق وسقف الاستجابة من دليل LiteLLM، ولا توجد معرفات شبكة Gonka فيه (لقد تحققنا من LiteLLM 1.81)، لذا لا يملك الوكيل قيمته الخاصة لهذه النماذج. هذا لا يعيق العمل: بوابة الشبكة تطبق سقف الاستجابة بنفسها وفقاً للجدول أعلاه. إذا أردت تعيين الحدود صراحةً - في SDK هي الحقول max_input_tokens و max_output_tokens، وفي Canvas تفتح علامة التبويب All المجموعة الكاملة من حقول ملف التعريف. تفاصيل النموذج الافتراضي موجودة في مراجعة DeepSeek V4 Flash.

يمكنك التحقق مما إذا كانت الطلبات تمر بالفعل عبر البوابة من جانبين. من جانب OpenHands: ابدأ محادثة جديدة بمهمة قصيرة مثل "اقرأ ملف README ولخصه في جملة واحدة": يجب أن يقوم الوكيل باستدعاء الأداة والرد. من جانب البوابة: في لوحة التحكم، قسم "الاستخدام" (Usage): سيظهر الطلب في تصنيف "حسب النماذج"، وسيتم تحديث وقت آخر طلب في كتلة "حسب المفاتيح". إذا كان فارغاً، فهذا يعني أن المحادثة تجري على ملف تعريف آخر: تحقق من أي منهم محدد كنشط.

وفقاً لوثائق OpenHands، يتم ضبط عدد المحاولات وفترات الانتظار بينها عند الخطأ 429 عبر المتغيرات LLM_NUM_RETRIES و LLM_RETRY_MIN_WAIT و LLM_RETRY_MAX_WAIT. تختلف القيم الافتراضية في الوثائق عنها في SDK، لذا اعتمد على القيم الفعلية: في حالة محادثة CLI 1.16.0، رأينا 5 محاولات مع فترات انتظار من 8 إلى 64 ثانية.

عبر JoinGonka Gateway تبلغ تكلفة الرموز (tokens) $0.0069 للمليون في المدخلات و $0.021 للمليون في المخرجات — السعر موحد لجميع نماذج الشبكة ويتم استجلابه في هذه الصفحة من مصدر حي.

التقديرات في العمود الأيمن تعتمد على أسعار سبتمبر 2026؛ تم شرح اقتصاديات الوكلاء بالتفصيل في المقالة حول أرخص API لوكلاء AI.

سقف الاستهلاك. ينصح OpenHands بوضع حدود للإنفاق — في البوابة مدمج هذا في نموذج الدفع نفسه: الرصيد مدفوع مسبقاً، ولن ينفق الوكيل أكثر مما هو موجود في الحساب. الرصيد المتبقي والاستهلاك اليومي مرئيان في لوحة التحكم. بالنسبة لـ CI والأتمتة الخلفية، قم بإنشاء مفتاح منفصل حتى لا يختلط استهلاكهم باستهلاكك؛ تم وصف المفاتيح الفرعية بحد يومي في المقالة حول Management Keys.

حدود الثقة. يعمل Agent Canvas الذي يتم تشغيله عبر npm بصلاحيات مستخدمك ويمكنه رؤية نظام الملفات بالكامل. بالنسبة للكود الخارجي، استخدم خيار Docker: سيرى الوكيل فقط المجلد المثبت. هذه خاصية في OpenHands نفسه، ولا تعتمد على موفر النموذج.

المراسلات تبقى لديك. يحتفظ OpenHands بسجل المحادثة محلياً، في ~/.openhands، ويرسله للنموذج مع كل خطوة؛ البوابة لا تحتفظ بالمراسلات — مدخلاتك (prompts) والكود لا تبقى عليها بعد الرد.

إذا كانت المهمة تحتوي على صور — لقطات شاشة للواجهة، مخططات — أنشئ لها ملف تعريف منفصل مع نموذج رؤية (vision-model): نماذج شبكة Gonka الحالية هي نماذج نصية. بالنسبة للكود والأوامر والملفات، هذا ليس قيداً.