كيفية إعداد Hermes Slack على ZimaOS وإصلاح أخطاء البوابة وتجهيزها

يمكن لـ Hermes Agent الاتصال بـ Slack دون كشف نقطة نهاية عامة لخطاف الويب، لأن تكامله الحالي مع Slack يستخدم وضع Socket. وقد وصل تقرير المجتمع الذي يستند إليه هذا المقال إلى معظم خطوات الإعداد بنجاح: أنشأ المستخدم تطبيق Slack جديدًا، وحصل على رمز xoxb- رمز مستخدم آلي ورمزًا xapp- رمزًا على مستوى التطبيق، ثم شغّل hermes gateway setup داخل حاوية ZimaOS Hermes، ودعا المستخدم الروبوت إلى قناة في Slack.

حدث الفشل عندما حاول Hermes إعادة تشغيل بوابته. أعاد سطر الأوامر PermissionError: [Errno 13] Permission denied: '/opt/data/gateway.lock'، وعلى الرغم من أن التطبيق ظهر في Slack، فإن @Hermes لم يُنتج الاستدعاء أي رد. وتحدد وثائق ZimaSpace الحالية صراحةً /opt/data اعتبرت أخطاء الأذونات مشكلة ملكية في Hermes يمكن أن تحدث بعد تنفيذ عمليات البوابة سابقًا بصلاحيات الجذر. وتضيف وثائق Hermes الحالية الخاصة بـ Slack أيضًا عدة متطلبات للإعداد يُعد التحقق منها أكثر أمانًا من تخمين النطاقات يدويًا.

ما حدث في تقرير ZimaOS Hermes عن Slack

استخدم منشور المجتمع في مايو 2026 تثبيتًا نظيفًا لـ ZimaOS Hermes ومساحة عمل Slack جديدة. أنشأ المستخدم تطبيق Slack مع تفعيل وضع Socket، ونسخ نوعي الرموز المطلوبين، ثم أعد إعداد Slack من خلال معالج بوابة Hermes.

كان التسلسل الأساسي هو:

1. أنشئ تطبيق Slack وفعّل وضع Socket.
2. احصل على رمز OAuth للمستخدم الآلي يبدأ بـ xoxb-.
3. احصل على رمز على مستوى التطبيق يبدأ بـ xapp-.
4. شغّل hermes gateway setup داخل حاوية Hermes.
5. حدّد Slack وأدخل الرمزين.
6. وافق على المطالبة بإعادة تشغيل البوابة.

فشلت إعادة التشغيل بالخطأ:

PermissionError: [Errno 13] Permission denied: '/opt/data/gateway.lock'

ثم أعاد المستخدم تشغيل البوابة من واجهة Hermes على الويب، ودعا @Hermes إلى قناة في Slack، وشاهد تأكيد Slack إضافة التطبيق. ومع ذلك، لم يتلقَ استدعاء التطبيق في القناة أي رد. وهذا يعني أنه كان هناك مستويان محتملان لاستكشاف الأخطاء وإصلاحها: عملية البوابة على جانب ZimaOS وإعدادات الأحداث على جانب Slack.

استخدم بيان Hermes الحالي لـ Slack بدلًا من إعادة إنشاء كل نطاق يدويًا

توصي وثائق Hermes الحالية بإنشاء بيان لتطبيق Slack. وهذا أكثر أمانًا من إعادة إنشاء كل نطاقات OAuth وأوامر الشرطة المائلة واشتراكات الأحداث وإعدادات وضع Socket يدويًا من الذاكرة.

داخل بيئة Hermes الحالية، أنشئ البيان باستخدام:

hermes slack manifest --agent-view --write

يُكتب الملف المُنشأ إلى:

~/.hermes/slack-manifest.json

ثم أنشئ تطبيق Slack جديدًا من ذلك البيان في واجهة إدارة التطبيقات في Slack. توضّح وثائق Hermes الحالية أن البيان يعلن معًا عن الأوامر المضمّنة، والنطاقات المطلوبة، واشتراكات الأحداث، وإعداد وضع المقابس.

للاطلاع على الإجراء الحالي من المصدر الرئيسي، راجع دليل إعداد Hermes Agent في Slack.

الرمزان المميّزان اللذان يحتاج إليهما Hermes في Slack

يستخدم Hermes بيانات اعتماد مختلفة لـ Slack، ولا يمكن استخدام أحدهما بدل الآخر:

• رمز الروبوت المميّز: يبدأ بـ xoxb- ويصبح SLACK_BOT_TOKEN.
• الرمز المميّز على مستوى التطبيق: يبدأ بـ xapp-، ويجب أن يدعم وضع المقابس، ويصبح SLACK_APP_TOKEN.

يمكن أن يحتوي ملف بيئة Hermes الحالي على:

SLACK_BOT_TOKEN=xoxb-your-bot-token
SLACK_APP_TOKEN=xapp-your-app-token
SLACK_ALLOWED_USERS=U01ABC2DEF3

SLACK_ALLOWED_USERS يستخدم Hermes معرّفات أعضاء Slack، وليس أسماء العرض. إذا كانت الرموز المميّزة صحيحة لكن المستخدم الطالب غير مسموح له، فقد يظل Hermes ظاهرًا على أنه متصل، مع رفضه معالجة رسائل ذلك المستخدم.

لا تنشر أبدًا xoxb- أو xapp- القيم في منشور مجتمعي أو لقطة شاشة أو مستودع Git أو سجل دعم. أبطِل الرمز المميّز وأنشئ رمزًا جديدًا إذا تم كشفه.

تتطلب الإشارات في القنوات أحداث Slack الصحيحة

لا يُثبت ظهور الروبوت في القناة أن Slack يرسل أحداث الرسائل إلى Hermes. وتشير وثائق Hermes الحالية إلى أن اشتراكات الأحداث سبب شائع للأعطال.

بالنسبة إلى تطبيق Slack المُعدّ يدويًا، تحقّق من الأحداث المطلوبة في الإصدار الحالي من Hermes. تتضمن الوثائق الحالية أحداثًا مثل:

• app_mention مباشرة @Hermes الإشارات.
• message.channels للرسائل في القنوات العامة التي يكون الروبوت عضوًا فيها.
• message.groups عند الحاجة إلى دعم القنوات الخاصة.
• message.im للرسائل المباشرة.

إذا غيّرت النطاقات أو اشتراكات الأحداث بعد تثبيت تطبيق Slack، فأعِد تثبيت التطبيق في مساحة العمل عندما يطلب Slack ذلك. وإلا فقد تختلف الإعدادات المعروضة عن الأذونات الممنوحة فعليًا للروبوت المثبّت.

أضِف Hermes إلى القناة قبل الاختبار

لا ينضم Hermes تلقائيًا إلى كل قناة في Slack. أضِفه صراحةً:

/invite @Hermes

ثم اختبر إشارة بسيطة من مستخدم Slack يكون معرّف عضويته مُدرجًا في قائمة السماح في Hermes. إذا كانت الرسائل المباشرة تعمل، لكن الإشارات في القنوات العامة لا تعمل، فركّز على app_mention, message.channels، وعضوية القناة، وأذونات التطبيق المثبّت قبل تغيير إعدادات الشبكة في ZimaOS.

لماذا يمكن أن يُرجع /opt/data/gateway.lock خطأ «تم رفض الإذن»

يوثّق دليل ZimaSpace لـ Hermes Agent الحالي الآن مشكلة أذونات /opt/data. ويذكر أن السبب المعتاد هو تشغيل Hermes Gateway بصلاحيات الجذر سابقًا، ما أدى إلى ترك ملفات مملوكة للجذر داخل $HERMES_HOME.

تتمثل آلية العمل الموثّقة في ZimaSpace للدخول إلى الحاوية في الدخول بصفتك hermes المستخدم:

docker exec -it -u hermes hermes bash

ثم فعّل البيئة الافتراضية لـ Hermes:

source /opt/hermes/.venv/bin/activate

يمكن بعد ذلك فتح إعدادات المراسلة باستخدام:

hermes gateway setup

إذا فشلت البوابة فورًا عند تنفيذ /opt/data/gateway.lockولا تشغّل البوابة بالكامل بصلاحيات الجذر بشكل متكرر. تحقّق أولًا من الهوية والملكية المعنيتين:

id
ls -ld /opt/data
ls -l /opt/data/gateway.lock 2>/dev/null

يوصي دليل ZimaSpace الحالي بالتحقق من سجلات Hermes في لوحة معلومات ZimaOS، وباستخدام جلسة طرفية بصلاحيات الجذر مؤقتًا فقط عند الحاجة إلى إصلاح ملكية الملفات. لا تطبّق تغيير ملكية عوديًا أعمى على /opt/data ما لم تتحقق من الملفات التي تخص Hermes ومن المستخدم/المجموعة التي تتوقعها حزمة ZimaOS المثبّتة.

أعد تشغيل البوابة فقط بعد أن يتمكن Hermes من الكتابة إلى ملفات وقت التشغيل الخاصة به

في تقرير المجتمع، لم يكن النقر على Restart Gateway في واجهة الويب كافيًا لإثبات أن البوابة تعمل بشكل سليم. فإذا تعذّر على العملية الأساسية إنشاء ملف القفل أو تحديثه، فقد يظل تكامل Slack غير متاح رغم تنفيذ إجراء واجهة المستخدم.

بعد تصحيح مشكلة الملكية الفعلية، ادخل إلى الحاوية بصفتك hermes المستخدم، ثم فعّل البيئة وشغّل البوابة أو أعد تشغيلها باستخدام الأوامر التي يدعمها إصدار Hermes المثبّت لديك. راقب سجلات Hermes في ZimaOS أثناء إرسال رسالة اختبار إلى Slack.

من المفيد تقسيم استكشاف الأخطاء وإصلاحها إلى:

• لا تبدأ البوابة: تحقّق من أذونات /opt/data وسجلات Hermes.
• تعمل البوابة، لكن لا يوجد اتصال بـ Slack: تحقّق من الرمز المميز xapp- ومن وضع Socket Mode.
• يوجد اتصال بـ Slack، لكن إشارات القناة صامتة: تحقّق من أحداث التطبيق، وعضوية القناة، وحالة إعادة التثبيت، وSLACK_ALLOWED_USERS.
• تعمل الرسائل المباشرة، لكن القناة لا تعمل: ركّز على أحداث القناة والأذونات بدلًا من مزوّد النموذج.

استخدم لوحة معلومات Hermes على الويب لمعرفة الحالة، وليس كفحص الصحة الوحيد

يعرض دليل ZimaSpace لوحة معلومات Hermes على الويب في:

http://ZIMAOS_LAN_IP:9119

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

قائمة التحقق لاستكشاف مشكلات Hermes مع Slack على ZimaOS

1. تأكّد من أن إعداد نموذج Hermes نفسه يعمل قبل إضافة Slack.
2. ادخل إلى حاوية ZimaOS بصفتك hermes مستخدمًا، وليس بصفة root، لتشغيل البوابة العادي.
3. استخدم بيان Hermes الحالي الخاص بـ Slack متى أمكن بدلًا من تخمين النطاقات يدويًا.
4. تأكّد من أن xoxb- رمز الروبوت و xapp- ينتمي رمز التطبيق إلى تطبيق Slack المستهدف نفسه.
5. تأكّد من تفعيل Socket Mode.
6. تأكّد من وجود معرّف عضو Slack الخاص بك ضمن SLACK_ALLOWED_USERS.
7. ادعُ Hermes إلى القناة التي تختبرها.
8. تحقّق من app_mention وتحقّق من الاشتراك في أحداث الرسائل المطلوبة.
9. أعد تثبيت تطبيق Slack بعد تغيير النطاقات أو اشتراكات الأحداث عندما يطلب Slack ذلك.
10. إذا /opt/data/gateway.lock يفشل، فتحقّق من الملكية وسجلات Hermes في ZimaOS قبل إعادة التشغيل مجددًا.
11. بعد أن تصبح البوابة سليمة، اختبر رسالة مباشرة وذكرًا واحدًا في قناة، كلًّا على حدة.

الأسئلة الشائعة حول Hermes مع Slack على ZimaOS

ماذا يعني خطأ أذونات gateway.lock؟

يعني ذلك أن عملية Hermes لا تستطيع الوصول إلى ملف قفل وقت التشغيل في الموقع المتوقع. وتذكر وثائق ZimaSpace الحالية أن /opt/data يرتبط خطأ الأذونات عادةً بملفات أصبحت مملوكة لـ root بعد تشغيل Hermes Gateway بصفة root.

هل ينبغي تشغيل Hermes Gateway بصفة root لإصلاح ذلك؟

ليس كحل عادي. توثّق ZimaSpace الدخول إلى الحاوية باعتبارك hermes مستخدمًا لعمليات Hermes العادية. ينبغي استخدام جلسة root مؤقتًا فقط بعد التأكد من ضرورة إصلاح الملكية.

لماذا يظهر روبوت Hermes في Slack لكنه لا يرد؟

لا يثبت التثبيت والدعوة إلا أن Slack يعرف التطبيق. ما يزال Hermes يحتاج إلى بوابة سليمة، واتصال Socket Mode صالح، واشتراكات أحداث صحيحة، وأذونات مناسبة لمساحة العمل، ومعرّف عضو Slack مسموحًا به.

هل يحتاج Hermes مع Slack إلى عنوان URL عام لخطاف الويب؟

لا. يستخدم تكامل Hermes مع Slack حاليًا وضع Socket Mode عبر WebSockets، لذا يمكن أن يبقى مثيل Hermes خلف جدار ناري من دون نقطة نهاية عامة لخطاف Slack الوارد.

ما أفضل طريقة حالية لتهيئة تطبيق Slack؟

استخدم بيان Slack المُنشأ حاليًا بواسطة Hermes عندما يدعمه إصدار Hermes المثبّت لديك. فهذا يقلل الأخطاء الناتجة عن النطاقات المفقودة أو اشتراكات الأحداث أو تعريفات أوامر الشرطة المائلة.