Goose + JoinGonka Gateway: الموفر الخاص والمفتاح في keyring

الخطوة 1: تثبيت Goose. الطرق الرسمية للـ CLI من وثائق المشروع:

# macOS and Linux: the script puts the binary in ~/.local/bin
curl -fsSL https://github.com/aaif-goose/goose/releases/download/stable/download_cli.sh | CONFIGURE=false bash

# macOS, Homebrew
brew install block-goose-cli

المتغيّر CONFIGURE=false يعطّل معالج goose configure الذي يشغّله السكربت تلقائياً بعد التثبيت: فسيقوم المُثبِّت بضبط المزوّد. وإذا لم يكن المجلد ~/.local/bin ضمن PATH، سيقول السكربت ذلك صراحة. لـ Windows يوجد في المستودع نفسه سكربت download_cli.ps1، أما تطبيق سطح المكتب فيُحمَّل من صفحة الوثائق؛ وهو والـ CLI يقرآن الإعدادات ذاتها، لذا فكل ما يلي ينطبق عليهما معاً. للتحقق — goose --version.

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

الخطوة 3: تشغيل المُثبِّت.

npx @joingonka/setup --tool goose

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

• ينشئ ملف المزوّد custom_providers/custom_joingonka.json بعنوان البوابة وثلاثة نماذج من الشبكة بنوافذ سياق حقيقية، مع صلاحيات 600. الاسمان custom_joingonka وCUSTOM_JOINGONKA_API_KEY — هما نفسهما اللذان يستنتجهما Goose تلقائياً من اسم "JoinGonka"، لذا سيقع المفتاح من المعالج في مكانه الصحيح؛
• يجعل JoinGonka المزوّد الافتراضي مع نموذج DeepSeek V4 Flash — لكن فقط إذا لم يكن المزوّد قد اختير بعد أو كان المختار مزوّدنا بنموذج فارغ أو غادر الشبكة. أما اختيار شخص آخر فلا يمسّه، بل يطبع أمراً للتجربة: goose session --provider custom_joingonka --model …؛
• يضع المفتاح في secrets.yaml، فقط إذا كان مخزن الأسرار عند Goose ملفّياً بشكل مؤكد؛ وإلا فسيقول صراحة إن بقيت خطوة واحدة — التفاصيل في قسم المفتاح؛
• ينشئ نسخاً احتياطية للملفات المعدَّلة، وفي النهاية يرسل طلباً حياً إلى البوابة للتحقق فوراً من المفتاح والعنوان والنموذج.

يعثر المُثبِّت على مجلد الإعدادات بالطريقة ذاتها التي يعتمدها Goose نفسه: ~/.config/goose على Linux و macOS، و%APPDATA%\Block\goose\config على Windows، و<root>/config عند تعيين GOOSE_PATH_ROOT. لتعيين نموذج آخر استخدم العلم --model مع الاختصار deepseek أو glm أو minimax؛ والنموذج المحدَّد صراحةً يُكتب دائماً. أما الوضع دون أسئلة فيأخذ المفتاح من متغيّر البيئة:

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

كل ما يقوم به المثبت يمكن القيام به يدويًا. المزود عبارة عن ملف JSON منفصل ~/.config/goose/custom_providers/custom_joingonka.json؛ اسم الملف يطابق الحقل name:

{
  "name": "custom_joingonka",
  "engine": "openai",
  "display_name": "JoinGonka",
  "description": "JoinGonka Gateway — Gonka AI inference (OpenAI-compatible)",
  "api_key_env": "CUSTOM_JOINGONKA_API_KEY",
  "base_url": "https://gate.joingonka.ai/v1/chat/completions",
  "models": [
    { "name": "deepseek-ai/DeepSeek-V4-Flash-0731", "context_limit": 380000 },
    { "name": "zai-org/GLM-5.3-Flash", "context_limit": 390000 },
    { "name": "MiniMaxAI/MiniMax-M2.7", "context_limit": 200000 }
  ],
  "supports_streaming": true,
  "requires_auth": true
}

لا يوجد سقف رد منفصل لسجل نموذج Goose. بالنسبة لهذه النماذج، هو لا ينقل القيد في الطلب على الإطلاق — وقد تحققنا من ذلك من خلال سجل الطلبات الخاص به — وفي وضع التدفق، تقوم البوابة نفسها بتقييد الرد بسقف النموذج: 32,768 توكن لـ DeepSeek V4 Flash، و 8192 لـ GLM-5.3 Flash و MiniMax M2.7. لا تحتاج إلى تعيين متغير عام GOOSE_MAX_TOKENS لهذا: فهو واحد لجميع المزودين في وقت واحد.

يقرأ Goose ملف المزود عبر تحليل JSON صارم: تعليق أو فاصلة زائدة تعني اختفاء المزود من القائمة. يمكنك إنشاؤه عبر المعالج (goose configure → Custom Providers)، لكن المعالج لا يسأل عن نافذة السياق — سيتعين عليك إضافتها يدويًا.

يعيش المزود والنموذج الافتراضي في ~/.config/goose/config.yaml. هكذا يسجلهم Goose بنفسه:

active_provider: custom_joingonka
providers:
  custom_joingonka:
    enabled: true
    model: deepseek-ai/DeepSeek-V4-Flash-0731
    configured: true

التنسيق القديم — المفاتيح المسطحة GOOSE_PROVIDER و GOOSE_MODEL في جذر الملف — يعمل أيضًا: يقرأه Goose ويقوم بتحويله بنفسه إلى التنسيق الجديد عند حفظ الإعدادات لأول مرة، كما حدث لدينا بعد goose configure. يقوم المثبت على ملف فارغ بكتابة مفاتيح مسطحة — تفهمها أي نسخة. متغيرات البيئة التي تحمل نفس الاسم لها أولوية على الملف: إذا تم تعيينها في shell، فلن يسري الاختيار من config.yaml، وسيحذر المثبت من ذلك.

في ملف المزوِّد لدى Goose لا يوجد سوى اسم السر — CUSTOM_JOINGONKA_API_KEY. ويبحث عن القيمة بالترتيب: في متغير البيئة الذي يحمل هذا الاسم، ثم في مخزن الأسرار في النظام (keyring، وفي macOS هو Keychain)، ثم في ملف secrets.yaml المجاور لملف الإعدادات. ولا تصل الأسرار إلى الملف إلا عندما يكون مخزن Goose ملفيًّا، حيث تُخزَّن كنص صريح بصلاحيات 600. أما في config.yaml فلا يبحث Goose عن المفاتيح إطلاقًا (التوثيق).

يتحوّل المخزن إلى ملفي إذا كان keyring معطّلًا — عبر المتغير GOOSE_DISABLE_KEYRING بأي قيمة كانت، أو السطر GOOSE_DISABLE_KEYRING: true في config.yaml — أو إذا كان غير متاح: خادم بلا جلسة رسومية، حاوية، CI. وفي الحالة الثانية يكتب Goose في السجل «Keyring unavailable. Using file storage for secrets.» وينتقل من تلقاء نفسه إلى الملف — وهذا بالضبط ما رأيناه في الحاوية. فالمثبِّت لا يستطيع الكتابة إلى keyring، ولن يعطّله نيابةً عنك: عندها يتوقف Goose عن رؤية الأسرار الموجودة فيه أصلًا. ومن هنا تأتي السيناريوهات:

الخطوة المتبقية. شغّل goose configure وأجب عن أسئلة المعالج — هكذا ظهرت في تجربتنا:

• What would you like to configure? → Configure Providers;
• Which model provider should we use? → JoinGonka (كان في الصدارة عندنا)؛
• Would you like to set CUSTOM_JOINGONKA_API_KEY? (optional) → Yes، ثم عند Enter value for CUSTOM_JOINGONKA_API_KEY الصق المفتاح — وستظهر مربعات مكان الأحرف. ويُحفظ المفتاح فورًا؛
• Would you like to configure advanced settings? → No;
• Select a model — يحصل Goose على القائمة من البوابة: MiniMaxAI/MiniMax-M2.7، deepseek-ai/DeepSeek-V4-Flash-0731، zai-org/GLM-5.3-Flash. والمؤشر واقف على السطر الأول — لإبقاء الموديل الذي اختاره المثبِّت، اختر بالأسهم DeepSeek V4 Flash. وبعد طلب تحقُّقي ينهي المعالج بسطر «Configuration saved successfully».

وفي Goose Desktop يكون المسار هكذا: Settings → Models → Configure providers → JoinGonka → المفتاح → Submit. وإن لم ترغب في لصق المفتاح يدويًّا، فضعْه في متغير وشغّل المعالج من الصدفة نفسها: سيكتب Goose «CUSTOM_JOINGONKA_API_KEY is set via environment variable» ويعرض حفظ القيمة:

read -s CUSTOM_JOINGONKA_API_KEY && export CUSTOM_JOINGONKA_API_KEY
goose configure

ولتشغيل واحد يمكنك تمرير المفتاح دون حفظه إطلاقًا: CUSTOM_JOINGONKA_API_KEY=jg-your-key goose session، وفي PowerShell: $env:CUSTOM_JOINGONKA_API_KEY = "jg-your-key"; goose session. ومتغير البيئة أرجح من القيمة المحفوظة، لكنه لا يعيش إلا حتى إغلاق الصدفة.

أولاً، اطّلع على الإعدادات التي يراها Goose فعلياً:

goose info -v

في كتلة «goose Configuration» يجب أن يكون هناك السطران GOOSE_PROVIDER: custom_joingonka وGOOSE_MODEL مع معرّف النموذج. بعد ذلك — تشغيل لمرة واحدة بدون جلسة تفاعلية: ضع في مجلد فارغ ملفاً يحتوي على خطأ واضح واطلب منه أن يجده.

goose run --no-session -t "Read calc.py and tell me in one sentence whether it has a bug."

الخيار --no-session لا يحفظ التشغيل في السجل. سيظهر في الأعلى سطر بالشكل ● new session · custom_joingonka deepseek-ai/DeepSeek-V4-Flash-0731، ثم استدعاء الأداة — ▸ shell مع الأمر cat calc.py — ثم الرد مع الخطأ المكتشف. لتحديد نموذج آخر لتشغيل واحد استخدم --model: zai-org/GLM-5.3-Flash أو MiniMaxAI/MiniMax-M2.7. في تشغيلنا بتاريخ 23 سبتمبر 2026، أكملت النماذج الثلاثة في الشبكة دورة «طلب ← أداة ← نتيجة ← رد». يُخفي CLI Goose استدلالات النماذج افتراضياً — ويمكن إظهارها عبر المتغير GOOSE_CLI_SHOW_THINKING=1 إذا كان الإخراج إلى الطرفية. من جهة البوابة يظهر الطلب في لوحة التحكم: قسم «الاستخدام»، وتفصيل «حسب النماذج» و«حسب المفاتيح».

إذا حدث خطب ما، فعادةً ما يُقرأ التشخيص مباشرة من الرسالة:

ينفق الوكيل (agent) التوكنات بشكل مختلف عن الدردشة. في الإعدادات الافتراضية، يرسل Goose للنموذج وصفاً لثماني عشرة أداة مدمجة، وفي تشغيلنا استهلكت كل خطوة حوالي 4.6 ألف توكن إدخال قبل طرح سؤالك. مهمة «قراءة ملف والعثور على خطأ» استغرقت خطوتين إلى ثلاث و 10-15 ألف توكن، معظمها إدخال؛ يقوم Goose بنفسه بطلب قصير آخر لتسمية الجلسة. يمكن إيقاف الامتدادات غير الضرورية عبر goose configure → Toggle Extensions — هذه هي أسهل طريقة لتقليل الإدخال.

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

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

الاستهلاك الدقيق والرصيد المتبقي موجودان في لوحة التحكم، في أقسام «الاستخدام» و «الفواتير». تم شرح سبب اختيار DeepSeek V4 Flash كنموذج افتراضي — مع أكبر سقف للاستجابة في الشبكة — بالتفصيل في مراجعة النموذج.

وضع التأكيدات. يعمل Goose افتراضياً في الوضع auto — استقلال تام: يعدّل الملفات ويحذفها، ويشغّل الأوامر، ويستخدم الإضافات دون أن يسأل عن شيء. هذا مريح في مشروعك، لكن مع كود الآخرين يُستحسن تشديد الوضع:

# inside a session
/mode smart_approve

# permanently, as a line in config.yaml
GOOSE_MODE: smart_approve

هذه خاصية Goose نفسه، ولا تعتمد على مزوّد النموذج.

تغيير النموذج. داخل الجلسة — الأمر /model مع المعرّف، مثل /model zai-org/GLM-5.3-Flash؛ لتشغيل واحد — العلَم --model لدى goose run وgoose session؛ بشكل دائم — goose configure أو سطر model في config.yaml. ويبقى المزوّد كما هو. نموذج GLM-5.3 Flash المفكّر جيد للمنطق المعقّد، لكن سقف رده 8192 توكن، ويذهب جزء منه إلى الاستدلال — التفاصيل في مراجعة النموذج.

تشغيلات دون إشراف. goose run مناسب للسكربتات وCI: العلَم -q يبقي في الإخراج رد النموذج فقط، و--output-format json يعطي النتيجة للتحليل. والقيود --max-turns (كم دوراً ينفّذه الوكيل دون تدخل بشري) و--max-tool-repetitions (كم مرة متتالية يمكن استدعاء أداة واحدة بالوسائط ذاتها) تحمي من الدوران في حلقة.

الخصوصية. إحصاءات الاستخدام المجهولة في Goose معطّلة افتراضياً (GOOSE_TELEMETRY_ENABLED). البوابة لا تحفظ محتوى الأوامر والردود — ولا يبقى في الإحصاءات سوى مجاميع الاستهلاك.