Factory Droid + JoinGonka Gateway: استخدام BYOK على نماذج شبكة Gonka

الخطوة 1: تثبيت Droid. الطرق الرسمية من توثيق Factory:

# macOS and Linux
curl -fsSL https://app.factory.ai/cli | sh

# Homebrew
brew install --cask droid

# Windows (PowerShell)
irm https://app.factory.ai/cli/windows | iex

# via npm
npm install -g droid

يضع السكربت الملف التنفيذي في ~/.local/bin ويرشدك إلى طريقة إضافة المجلد إلى PATH؛ وعلى Linux يطلب التوثيق تثبيت حزمة xdg-utils أيضاً. للتحقق استخدم droid --version.

الخطوة 2: الحصول على المفتاح. سجّل في gate.joingonka.ai/register، وأكّد بريدك، وأنشئ مفتاحاً بالبادئة jg- من قسم "مفاتيح API". مفتاح واحد ورصيد واحد يكفيان لجميع نماذج الشبكة.

الخطوة 3: تشغيل برنامج التثبيت.

npx @joingonka/setup --tool droid

سيسألك برنامج التثبيت عن المفتاح — فلا يُمرَّر في وسائط سطر الأوامر حتى لا يبقى في سجل الصدفة — وسيقوم بأربعة أمور:

• يضيف إلى مصفوفة customModels في ملف ~/.factory/settings.json (وعلى Windows: %USERPROFILE%\.factory\settings.json) سجلاً لكل نموذج من نماذج الشبكة: عنوان البوابة، ونوع المزوّد generic-chat-completion-api، والمفتاح نصاً صريحاً، ونافذة السياق الحقيقية وسقف الاستجابة؛ ويحصل الملف على صلاحيات 600؛
• يضبط النموذج الافتراضي — sessionDefaultSettings.model — على DeepSeek V4 Flash، لكن فقط إن لم يكن هناك نموذج مختار أو كان النموذج المختار قد غادر الشبكة. أما نموذج من كتالوج Factory أو سجل BYOK لشخص آخر فلا يتجاوزه، بل يرشدك إلى كيفية التبديل؛
• يحتفظ بنسخة من الملف السابق، ويترك سجلات الآخرين في customModels وبقية الإعدادات والتعليقات كما هي؛ والملف الذي يتعذّر تحليله لا يُعاد كتابته، بل يخبرك بما يجب إصلاحه؛
• في النهاية يرسل طلباً حياً إلى البوابة ويخبرك صراحةً هل قُبل المفتاح والعنوان والنموذج.

لتعيين نموذج افتراضي آخر استخدم العلم --model مع الاختصار deepseek أو glm أو minimax — والنموذج المحدد صراحةً يُكتب دائماً. ولملفات الإعداد والخوادم هناك وضع بلا أسئلة، يُؤخذ فيه المفتاح من متغير البيئة:

JOINGONKA_API_KEY=jg-your-key npx @joingonka/setup --tool droid --model glm --non-interactive

لا حاجة لإعادة تشغيل Droid: فهو يلاحظ التغييرات في settings.json بنفسه. أما السطر ! Could not verify right now مع استجابة 429 في النهاية فيعني أن النموذج مشغول، لا خطأ في الإعداد — فالتهيئة كُتبت بالفعل.

كل ما يفعله المثبِّت يمكن كتابته يدويًا. تُحفظ إعدادات المستخدم في Droid داخل ~/.factory/settings.json؛ وإذا لم يكن الملف موجودًا، ينشئه Droid عند أول تشغيل. ولشبكة Gonka تحتاج إلى المصفوفة customModels وإلى نموذج افتراضي:

{
  "customModels": [
    {
      "model": "deepseek-ai/DeepSeek-V4-Flash-0731",
      "id": "custom:deepseek-ai/DeepSeek-V4-Flash-0731",
      "displayName": "DeepSeek V4 Flash (Gonka)",
      "baseUrl": "https://gate.joingonka.ai/v1",
      "apiKey": "jg-your-key",
      "provider": "generic-chat-completion-api",
      "maxOutputTokens": 32768,
      "maxContextLimit": 380000,
      "noImageSupport": true
    },
    {
      "model": "zai-org/GLM-5.3-Flash",
      "id": "custom:zai-org/GLM-5.3-Flash",
      "displayName": "GLM 5.3 Flash (Gonka)",
      "baseUrl": "https://gate.joingonka.ai/v1",
      "apiKey": "jg-your-key",
      "provider": "generic-chat-completion-api",
      "maxOutputTokens": 8192,
      "maxContextLimit": 390000,
      "noImageSupport": true
    },
    {
      "model": "MiniMaxAI/MiniMax-M2.7",
      "id": "custom:MiniMaxAI/MiniMax-M2.7",
      "displayName": "MiniMax M2.7 (Gonka)",
      "baseUrl": "https://gate.joingonka.ai/v1",
      "apiKey": "jg-your-key",
      "provider": "generic-chat-completion-api",
      "maxOutputTokens": 8192,
      "maxContextLimit": 200000,
      "noImageSupport": true
    }
  ],
  "sessionDefaultSettings": {
    "model": "custom:deepseek-ai/DeepSeek-V4-Flash-0731"
  }
}

يُحفظ النموذج الافتراضي في sessionDefaultSettings.model ويشير إلى السجل عبر id الخاص به. وتذكر وثائق Factory أيضًا المفتاح model في جذر الملف، لكن في تجربتنا كان droid exec بدون العلَم -m يأخذ النموذج من sessionDefaultSettings تحديدًا — وكذلك بعد تغيير القيمة.

المفتاح موضوع في الملف كنص صريح: أغلق الملف بالأمر chmod 600 ~/.factory/settings.json ولا تنقل السجلات التي تحتوي على المفتاح إلى .factory/settings.json الخاص بالمشروع — فهو غالبًا ما ينتهي داخل المستودع. وإذا بدا الملف مختلفًا بعد تشغيل Droid، فهذا طبيعي: فعند حفظ أي إعداد يعيد Droid كتابة الملف بالكامل — يرتّب المفاتيح، ويضيف إلى السجلات الحقل index، ولا يحتفظ بالتعليقات. وتبقى الأذونات 600 كما هي، والمثبِّت يحدّث مثل هذه السجلات بلا مشكلة.

يعرض Droid تسجيلاته الخاصة بشكل منفصل عن الكتالوج: وفقًا للتوثيق، في الوضع التفاعلي يعرضها أمر /model في قسم Custom models، بينما يتنقل Ctrl+N بين النماذج مباشرة في حقل الإدخال. في وضع التشغيل لمرة واحدة، يُحدَّد النموذج عبر الراية -m بقيمة من الحقل id، وتُكتب الشرطات المائلة كما هي: droid exec -m custom:zai-org/GLM-5.3-Flash "…".

إذا أخطأت في الاسم، سيرد Droid بـ Invalid model ويسرد كل النماذج التي يراها، بما فيها نماذجك بصيغة custom:… (display name): وبذلك يظهر أيضًا أن التسجيلات قد حُمِّلت. أما الاسم على طريقة توثيق Factory، المكوَّن من التسمية والرقم (custom:DeepSeek-V4-Flash-(Gonka)-0)، فلن يعمل عند وجود id صريح — فقد أعطى في تجربتنا النتيجة نفسها Invalid model.

ما يتطلب حساب Factory. نماذجك الخاصة تحل مسألة دفع ثمن الرموز (tokens)، لكنها لا تحل مسألة الدخول إلى المنتج نفسه. إليك ما أظهرته تجربة تشغيل Droid 0.225.1 دون تسجيل الدخول إلى الحساب:

للعمل في الواجهة، أنشئ حساب Factory وسجِّل الدخول عبر المتصفح — عبر خيار Login أو الأمر /login؛ وعلى جهاز بلا متصفح، يقترح التوثيق استخدام مفتاح من إعدادات الحساب في المتغير FACTORY_API_KEY. تشغيل droid exec دون تسجيل دخول مريح للتجربة، لكنه غير موصوف رسميًا — فلا تعتمد عليه في CI. وفقًا لصفحة الأسعار في Factory، فإن BYOK مشمول في جميع الخطط الفردية بحد مجاني، وما يتجاوز الحد يُحتسب استخدام BYOK وفقًا لشروط الخطة؛ والشروط الحالية على factory.ai/pricing. أما رموز (tokens) نماذج الشبكة فتُدفع بشكل منفصل — من رصيد JoinGonka.

أي نموذج تختار. السعر واحد لجميع نماذج الشبكة، لذا يكون الاختيار متعلقًا بالسلوك. وهكذا عملت في تجربتنا لـ droid exec على مهمة واحدة — قراءة ملف والعثور على خطأ:

الراية -r (مستوى الاستدلال)، وفقًا لتوثيق Factory، لا تُطبَّق على نماذج BYOK. ولماذا اختير DeepSeek V4 Flash افتراضيًا، تجد التفصيل في مراجعة النموذج.

ضع في مجلد فارغ ملفّ calc.py يحتوي على خطأ واضح — مثلًا مساحة مستطيل تُجمع فيه الأضلاع بدلًا من ضربها — ثم اطلب من Droid أن يكتشفه:

droid exec "Read the file calc.py in the current project directory and tell me in one sentence whether it has a bug."

من دون أي أعلام، يعمل droid exec في وضع القراءة فقط: يمكنه النظر في الملفات، لا تعديلها. سيستدعي الوكيل أداة القراءة بنفسه ويجيب في صلب الموضوع، مع تحديد التعبير الخاطئ. ومع العلم -o json يأتي الرد ككائن واحد يسهل تحليله بسكربت (المخرجات مختصرة):

{"type":"result","subtype":"success","is_error":false,"duration_ms":2239,"num_turns":2,
 "result":"Yes, the file has a bug: the rectangle area is computed as the sum of the side lengths, but it should be their product (width * height). …",
 "usage":{"input_tokens":19016,"output_tokens":146,"factory_credits":0,"ttft_ms":747}}

يؤكد الحقل factory_credits: 0 أن العمل جرى على نموذجك أنت، لا على رصيد Factory. ولكي يتمكن الوكيل من تعديل الملفات، أضف مستوى من الاستقلالية: droid exec --auto low "Fix the bug in calc.py and change nothing else." — في تجربتنا، قرأت DeepSeek V4 Flash الملف، واستبدلت الجمع بالضرب، وشغّلت السكربت بنفسها للتأكد من أن الناتج هو 12.

التحقق الثالث — من جهة البوابة: في لوحة التحكم ضمن قسم «الاستخدام» سيظهر الطلب في تفصيل «حسب النماذج»، وفي كتلة «حسب المفاتيح» سيُحدَّث وقت آخر طلب.

إذا حدث خطب ما، ضع في الحسبان خصوصية Droid: في الكونسول لا يطبع droid exec سوى Error during droid execution: Exec failed (وفي JSON — "result":"Exec failed")، أما السبب الحقيقي فيبقى في السجل. ويمكن استخراجه بأمر واحد:

grep agent_error_count ~/.factory/logs/droid-log-single.log | grep -o '"errorMessage":"[^,]*' | tail -1

تستهلك أداة الوكيل التوكنات بشكل مختلف عن الدردشة: مع كل عبارة ترسلها، يضيف Droid مطالبة النظام (system prompt)، وأوصاف الأدوات، ولقطة لكتالوج العمل، وتستغرق المهمة عدة خطوات. في تجربتنا، كل خطوة استهلكت حوالي 9.5 ألف توكن مدخل قبل سؤالك: مهمة «قراءة ملف والعثور على خطأ» استغرقت خطوتين وحوالي 19 ألف توكن، و«الإصلاح والتحقق» — أربع خطوات وحوالي 44 ألف توكن. لذلك، السعر لكل توكن هنا هو العامل الحاسم.

من خلال JoinGonka Gateway، تكلف التوكنات $0.0069 لكل مليون توكن مدخل و $0.021 لكل مليون توكن مخرج — السعر متطابق لجميع نماذج الشبكة ويتم جلبه في هذه الصفحة من مصدر حي.

التقديرات في العمود الأيمن تعتمد على أسعار سبتمبر 2026. للمقارنة — كيف يمكنك الدفع مقابل النماذج في Droid:

يُظهر أمر /cost في واجهة Droid إحصائيات الجلسة، بينما الاستهلاك الدقيق والرصيد المتبقي لنماذج BYOK موجودان في حساب البوابة، في أقسام «الاستخدام» (Usage) و«الفواتير» (Billing). أنشئ مفتاحاً منفصلاً لـ Droid — سيظهر استهلاكه في سطر مستقل.

الاستقلالية. في الوضع لمرة واحدة، يقتصر Droid افتراضيًا على القراءة، وتوسّع المستويات الصلاحيات: --auto low — تعديل الملفات، --auto medium — إضافةً إلى تثبيت الاعتماديات والبناء والاختبارات والالتزامات المحلية، --auto high — حتى الدفع والنشر. ويلغي العلم --skip-permissions-unsafe كل الفحوص — للحاويات لمرة واحدة فقط. وفي الوضع التفاعلي يبدّل المستوى بـ Ctrl+L، أما المستوى الابتدائي فيحدده sessionDefaultSettings.autonomyLevel؛ وهو افتراضيًا off — أي كل شيء بتأكيد.

التوقيع في الالتزامات. الإعداد includeCoAuthoredByDroid مفعّل افتراضيًا: يضيف Droid إلى رسائل الالتزام سطر مشاركة في التأليف. وإن لم تكن بحاجة إليه، اكتب "includeCoAuthoredByDroid": false في settings.json.

أين تُحفظ الجلسات. بعد تسجيل الدخول إلى الحساب، يعكس Droid افتراضيًا جلسات CLI إلى نسخة Factory على الويب — ويتولى ذلك cloudSessionSync. ومفاتيح BYOK، بحسب الوثائق، تبقى محلية؛ وإن أردت أن تبقى المراسلات أيضًا على الجهاز، فاضبط "cloudSessionSync": false. والبوابة من جهتها لا تحفظ محتوى المطالبات والردود — ولا يبقى في الإحصاءات سوى مجاميع الاستهلاك.

التحديثات. التثبيت بالسكربت يحدّث نفسه؛ ويمكن تثبيت الإصدار بالمتغير FACTORY_DROID_AUTO_UPDATE_ENABLED=false أو بالأمر droid update --version <version>؛ أما البنيات من npm فلا تحدّث نفسها. وبعد التحديث، تحقق بأمر droid exec واحد من أن نماذج الشبكة في مكانها.

الصور. نماذج الشبكة نصية؛ ومن أجل لقطات الشاشة، أبقِ إلى جانبها إدخالًا بنموذج يجيد الرؤية، لدى مزوّد آخر.

إن كان العمل بلا حساب المزوّد أمرًا جوهريًا. تتصل نماذج الشبكة نفسها بوكلاء طرفية مفتوحة لا تحتاج إلى تسجيل دخول — مثل OpenCode بالمثبِّت نفسه، مع العلم --tool opencode.