الدرس 7: ملفات الإعداد

مرحبًا بعودتكم، يا مروّضي الوكلاء! في هذا الدرس، سنغوص في قلب Hermes: ملفات الإعداد. إذا سبق أن شعرتم بالضياع في بحر من YAML ومتغيرات البيئة، فلا تخافوا—سنجعل الأمر سهلاً قدر الإمكان.

القاعدة الرئيسية لـ Hermes

كل شيء يعيش في ~/.hermes/. اعتبروه شقة وكيلكم. إليكم ما بداخلها:

~/.hermes/
├── config.yaml     # الإعدادات (النموذج، الطرفية، TTS، الضغط، إلخ.)
├── .env            # مفاتيح API والأسرار
├── auth.json       # بيانات اعتماد مزود OAuth (Nous Portal، إلخ.)
├── SOUL.md         # الهوية الأساسية للوكيل (الفتحة #1 في موجه النظام)
├── memories/       # الذاكرة الدائمة (MEMORY.md، USER.md)
├── skills/         # المهارات التي أنشأها الوكيل (تُدار عبر أداة skill_manage)
├── cron/           # المهام المجدولة
├── sessions/       # جلسات البوابة
└── logs/           # السجلات (errors.log، gateway.log — الأسرار محذوفة تلقائيًا)

الطريق الأسهل: إعداد بأمر واحد

قبل أن نتعمق في التفاصيل، إليكم نصيحة محترفين: شغّلوا hermes setup --portal. تسجيل OAuth واحد يمنحكم مزود نموذج وأدوات بوابة الأربعة دون لمس أي ملف YAML. مشتركو Portal يحصلون أيضًا على خصم 10% على مزودي الفوترة بالرموز. إنها الطريقة الكسولة للبدء، ونحن نحبها.

إدارة إعداداتكم

يمنحكم Hermes مجموعة أدوات كاملة لإدارة الإعدادات. إليكم الأوامر التي ستستخدمونها يوميًا:

hermes config              # عرض الإعداد الحالي
hermes config edit         # فتح config.yaml في محرركم
hermes config get KEY      # طباعة قيمة محلولة
hermes config set KEY VAL  # تعيين قيمة محددة
hermes config unset KEY    # إزالة قيمة معيّنة من قبل المستخدم
hermes config check        # التحقق من الخيارات المفقودة (بعد التحديثات)
hermes config migrate      # إضافة الخيارات المفقودة بشكل تفاعلي

إليكم بعض الأمثلة العملية:

hermes config get model
hermes config set model anthropic/claude-opus-4
hermes config set terminal.backend docker
hermes config unset terminal.backend
hermes config set OPENROUTER_API_KEY sk-or-...  # يُحفظ في .env

الحيلة السحرية: hermes config set يوجّه القيم تلقائيًا إلى الملف الصحيح. مفاتيح API تذهب إلى .env، وكل شيء آخر يذهب إلى config.yaml. لا مزيد من التخمين!

ما الذي يفوز عند وجود تعارض؟

يحلّ Hermes الإعدادات بهذا الترتيب (الأولوية القصوى أولاً):

وسائط CLI — مثل hermes chat --model anthropic/claude-sonnet-4
~/.hermes/config.yaml — ملف الإعداد الأساسي لديكم
~/.hermes/.env — للأسرار (مفاتيح API، الرموز، كلمات المرور)
الافتراضيات المدمجة — قيم آمنة مكتوبة في الكود

قاعدة عامة: الأسرار تذهب إلى .env. كل شيء آخر يذهب إلى config.yaml. عندما يكون كلاهما معيّنًا، يفوز config.yaml للإعدادات غير السرية.

استبدال متغيرات البيئة

يمكنكم الإشارة إلى متغيرات البيئة في config.yaml باستخدام صيغة ${VAR_NAME}:

auxiliary:
  vision:
    api_key: ${GOOGLE_API_KEY}
    base_url: ${CUSTOM_VISION_URL}

delegation:
  api_key: ${DELEGATION_KEY}

المراجع المتعددة تعمل أيضًا: url: "${HOST}:${PORT}". إذا لم يكن المتغير معيّنًا، يبقى العنصر النائب كما هو ويتم تسجيل تحذير. صيغة Cursor-style ${env:VAR_NAME} تعمل أيضًا، لذا يمكنكم نسخ مقاطع من إعدادات Cursor أو Claude دون تعديل.

مهلات المزودين

يمكنكم تعيين مهلات لكل مزود ولكل نموذج:

providers:
  some-provider:
    request_timeout_seconds: 600
    models:
      some-model:
        timeout_seconds: 300

يوجد أيضًا stale_timeout_seconds لاكتشاف الاستدعاءات غير المتدفقة القديمة. هذه الإعدادات تتجاوز متغيرات البيئة القديمة HERMES_API_TIMEOUT وHERMES_API_CALL_STALE_TIMEOUT.

حدود وقت التشغيل

لأسطح الخادم طويلة التشغيل (البوابة، hermes serve --isolated)، يمكنكم تعيين حدود واصفات الملفات:

runtime:
  nofile_soft_limit: 4096

الافتراضي هو 4096. عيّنوه إلى 0 أو false أو null لتعطيل التعديل.

سلوك التحديث

إعدادات التحديث تعيش تحت updates في config.yaml:

updates:
  pre_update_backup: quick

الخلاصة

هذه كانت جولة الإعدادات! تذكروا: hermes setup --portal للطريق السهل، وhermes config set للتغييرات السريعة، واحفظوا الأسرار في .env. وكيلكم سيشكركم.

التالي: سنستكشف مزودي الذكاء الاصطناعي وكيفية ربط نماذجكم المفضلة. ترقبوا!