طريقة تثبيت Hermes Agent على Mac باستخدام Docker

يوضح هذا الدليل طريقة تشغيل Hermes Agent على جهاز Mac باستخدام Docker Desktop. الفكرة هي أن يعمل البرنامج داخل حاوية Docker، بينما تبقى الإعدادات والجلسات وبيانات المصادقة محفوظة في مجلد ثابت على جهازك.

يدعم Hermes Agent أكثر من طريقة لربط مزودات النماذج، بما في ذلك API key. لكن هذا الدليل يركز على OpenAI Codex باستخدام ChatGPT OAuth. الترتيب الأنسب هو تثبيت Docker Desktop، ثم تشغيل setup، ثم إعداد المزود، ثم تشغيل Hermes Agent، وبعدها التأكد من dashboard على localhost:9119.

المتطلبات

ما الذي يفعله Docker هنا؟

Hermes Agent هو runtime لوكلاء الذكاء الاصطناعي من NousResearch. تشرح الوثائق الرسمية أكثر من طريقة للاستخدام، منها local installation وDocker execution وDocker terminal backend. يركز هذا الدليل على تشغيل Hermes Agent نفسه داخل حاوية Docker.

الفائدة هي عزل بيئة التشغيل نسبياً. لا تحتاج إلى تثبيت Python وNode.js وbrowser automation dependencies والأدوات المرتبطة بها مباشرة داخل macOS. في المقابل، يجب أن يكون Docker Desktop قيد التشغيل أولاً، ويجب فهم الوصول إلى الملفات من خلال المجلدات التي تعمل لها mount بوضوح.

يستخدم Hermes Agent المسار /opt/data داخل الحاوية كمكان لبيانات المستخدم. لذلك نربط مجلد ~/.hermes على Mac بهذا المسار.

تثبيت Docker Desktop

نزّل Docker Desktop من صفحة التثبيت الرسمية الخاصة بـ Mac. اختر إصدار Apple Silicon لأجهزة M-series، أو إصدار Intel للأجهزة الأقدم.

الخطوات الأساسية هي:

1. تنزيل Docker Desktop من صفحة Mac الرسمية.
2. فتح Docker.dmg ونقل Docker إلى مجلد Applications.
3. تشغيل Docker Desktop من Applications.
4. مراجعة طلبات الصلاحيات وشاشة الشروط الأولية.
5. الانتظار حتى يصبح رمز Docker ثابتاً في شريط القوائم.

بعد ذلك تحقق من Terminal:

docker --version

إذا لم يظهر الأمر، فقد لا يكون Docker Desktop يعمل بعد، أو لم تكتمل تهيئة CLI.

لماذا نستخدم mount لـ ~/.hermes

Volume mount هو ما يمنع ضياع الإعدادات بعد حذف الحاوية. استخدم هذا الخيار في كل أوامر Hermes:

-v ~/.hermes:/opt/data

التشغيل الأول: setup wizard

أنشئ مجلد البيانات وشغّل setup:

mkdir -p ~/.hermes
docker run -it --rm \
  -v ~/.hermes:/opt/data \
  nousresearch/hermes-agent setup

الخيار --rm يحذف الحاوية المؤقتة بعد انتهاء الأمر، لكن الملفات التي تُنشأ في /opt/data تبقى داخل ~/.hermes.

قد ينشئ setup wizard ملفات ومجلدات مثل:

قد تختلف أسئلة setup حسب إصدار Hermes Agent، لكن القاعدة العملية للمبتدئين هي:

بمعنى آخر، دع setup ينشئ الملفات الأساسية أولاً. إذا كان اختيار المزود غير واضح، افتحه لاحقاً عبر hermes model.

بعد ذلك تحقق من المجلد:

ls -la ~/.hermes

تحقق أيضاً من وجود config.yaml. لا تنشر الملف كاملاً؛ يكفي فحص بدايته محلياً.

sed -n '1,80p' ~/.hermes/config.yaml

لا تطبع ملف .env ولا تشاركه لأنه قد يحتوي على secrets. للتحقق من وجوده فقط:

ls -la ~/.hermes/.env

إذا انتهى setup لكن ~/.hermes/config.yaml غير موجود أو كان المجلد فارغاً، فتحقق أولاً من volume mount. يجب أن يحتوي الأمر على -v ~/.hermes:/opt/data.

إعداد ChatGPT OAuth

إذا لم يتم اختيار المزود أثناء setup، افتح قائمة النماذج:

docker run -it --rm \
  -v ~/.hermes:/opt/data \
  nousresearch/hermes-agent model

اختر OpenAI Codex أو الخيار الأقرب إلى Codex. إذا ظهر رابط أو device code، افتحه في متصفح Mac وسجّل الدخول بحساب ChatGPT.

بعض الإصدارات تدعم أيضاً:

docker run -it --rm \
  -v ~/.hermes:/opt/data \
  nousresearch/hermes-agent auth add openai-codex --type oauth

لا ينبغي أن يبقى OAuth token داخل حاوية مؤقتة فقط. يتم حفظه داخل مجلد ~/.hermes الذي عملت له mount، مثلاً في auth store مثل auth.json. بهذا يمكنك إعادة إنشاء الحاوية من دون فقدان إعداد المزود.

تشغيل Hermes Agent

بعد setup وإعداد المزود، شغّل Hermes Agent تفاعلياً:

docker run -it --rm \
  -v ~/.hermes:/opt/data \
  nousresearch/hermes-agent

إذا فتحت الجلسة التفاعلية بشكل طبيعي، فهذا يعني أن الإعداد الأساسي يعمل. استمر في استخدام نفس volume mount مع كل أمر.

معنى الخيارات الأساسية:

التحقق من dashboard على localhost:9119

بعد نجاح setup وإعداد المزود والتشغيل التفاعلي، تحقق من الصورة والإصدار:

docker pull nousresearch/hermes-agent:latest
docker run -it --rm nousresearch/hermes-agent:latest version

وللتحقق من حالة OAuth استخدم نفس مجلد البيانات:

docker run -it --rm \
  -v ~/.hermes:/opt/data \
  nousresearch/hermes-agent auth list

لتشغيل gateway وdashboard في الخلفية:

docker run -d \
  --name hermes \
  --restart unless-stopped \
  -v ~/.hermes:/opt/data \
  -p 8642:8642 \
  -p 9119:9119 \
  -e HERMES_DASHBOARD=1 \
  nousresearch/hermes-agent gateway run

افتح http://localhost:9119 أو http://127.0.0.1:9119 في المتصفح. dashboard واجهة محلية لمراجعة الإعدادات والجلسات والسجلات وskills.

إذا لم تفتح الصفحة:

curl -I http://127.0.0.1:9119

وتعرض السجلات تفاصيل التشغيل:

docker logs --tail 50 hermes

قد تبدأ سجلات dashboard بالوسم [dashboard].

لإيقاف الحاوية الخلفية وحذفها:

docker stop hermes
docker rm hermes

مشكلات شائعة

على أجهزة Apple Silicon، يتعامل Docker Desktop غالباً مع اختلافات architecture ما لم تفرض صورة Intel-only. ابدأ بالصورة الرسمية latest وبإصدار حديث من Docker Desktop.

التحديث أو الحذف

للتحديث، اسحب أحدث صورة وأعد إنشاء الحاوية مع الحفاظ على ~/.hermes:

docker pull nousresearch/hermes-agent:latest
docker rm -f hermes
docker run -d \
  --name hermes \
  --restart unless-stopped \
  -v ~/.hermes:/opt/data \
  -p 8642:8642 \
  -p 9119:9119 \
  -e HERMES_DASHBOARD=1 \
  nousresearch/hermes-agent gateway run

لحذف الحاوية والصورة:

docker rm -f hermes
docker rmi nousresearch/hermes-agent:latest

احذف ~/.hermes فقط إذا أردت حذف الإعدادات وOAuth والجلسات وskills والسجلات أيضاً.

rm -rf ~/.hermes

الخلاصة

التسلسل العملي هو: Docker Desktop، ثم setup، ثم OpenAI Codex عبر ChatGPT OAuth، ثم mount لـ ~/.hermes:/opt/data، ثم فحص http://localhost:9119 عند تشغيل gateway.

المصادر

• Hermes Agent Docker documentation
• Hermes Agent Web Dashboard documentation
• Hermes Agent AI Providers documentation
• Hermes Agent Credential Pools documentation
• Hermes Agent installation documentation
• NousResearch Hermes Agent GitHub installation document
• NousResearch Hermes Agent GitHub repository
• Docker Desktop Mac installation documentation
• Docker Desktop Mac permission documentation
• Docker Hub nousresearch/hermes-agent image