💬

Module 04 — الموديول الرابع

منصات المراسلة

تيليجرام، ديسكورد، سلاك، واتساب، سيجنال، والبريد — بوابة واحدة لكلهم

15 Slides ثنائي اللغة تطبيق عملي

Slide 2 — بوابة المراسلة

إيه هي بوابة المراسلة؟

عملية خلفية واحدة تربط كل تطبيقات المراسلة بالوكيل

Gateway Architecture

[Telegram] [Discord] [Slack] [WhatsApp] [Signal] [Email] | | | | | | | | | | | | +----------+---------+----------+----------+--------+ | v +---------------------------------+ | Session Store | +---------------------------------+ | v +---------------------------------+ | AIAgent (model + tools) | +---------------------------------+ ^ | +---------------------------------+ | Cron Scheduler: tick 60s | +---------------------------------+

🧩

Adapter / محوّل

الكود المخصّص لكل منصة — بيعرف يقرأ ويكتب بلغة المنصة

🗂️

Session / جلسة

سجل محادثة مستقل لكل (منصة + محادثة + مستخدم)

📡

Long Polling

البوابة تسأل السيرفر عن الجديد — مفيش IP عام ولا webhook

🔌

Socket Mode

اتصال WebSocket ثنائي الاتجاه — المستخدم في Slack

ℹ️

مفيش bot لكل منصة

البوابة الواحدة هي الجسر بين كل تطبيقات المراسلة وقوة الذكاء الاصطناعي — والرد بيرجع دايماً على نفس المنصة اللي جاءت منها الرسالة.

Slide 3 — تيليجرام على OpenClaw

تيليجرام على OpenClaw

أسهل قناة للبداية — مفيش webhook ولا IP عام

1️⃣

أول خطوة: أنشئ البوت من @BotFather

افتح t.me/BotFather وابعت /newbot، اختار display name، وبعدها username فريد لازم ينتهي بحرف bot. هيدّيك token بالشكل ده — حافظ عليه سرّي، ولو اتسرّب ألغيه فوراً بـ /revoke.">

text — bot token

123456789:ABCdefGHIjklMNOpqrSTUvwxYZ

💡

الشرح: أضف القناة على OpenClaw وابدأ البوابة

الأمر ده بينشئ قناة تيليجرام ويخزّن الـ token، وبعدين شغّل الـ gateway. تيليجرام مش بيستخدم channels login — حُط الـ token في الـ config أو الـ env وشغّل.

bash

# أضف قناة تيليجرام بالـ token بتاعك
openclaw channels add --channel telegram --token <bot-token>

# شغّل البوابة
openclaw gateway

# اتأكد إن القناة جاهزة، وبعدين اقبل أول pairing
openclaw channels status --probe
openclaw pairing list telegram
openclaw pairing approve telegram <CODE>

⚠️

Privacy Mode في المجموعات

تيليجرام مفعّل الـ privacy افتراضياً، فالبوت مش بيشوف رسايل المجموعة العادية. إما تطفّيها من /mybots → Bot Settings → Group Privacy ثم تشيل البوت وتضيفه تاني، أو ترفعه admin في المجموعة.

Slide 4 — تيليجرام على Hermes

تيليجرام على Hermes

الطريقة التفاعلية الموصى بها — wizard كامل

💡

الشرح: شغّل الـ wizard واختار تيليجرام

الأمر ده بيفتح معالج إعداد خطوة بخطوة: تختار القناة، تحط الـ bot token، وتحدد المستخدمين المسموح لهم بالتواصل مع البوت.

bash

# معالج الإعداد التفاعلي — اختار Telegram
hermes gateway setup

# تشغيل في الـ foreground للتجربة الأولى
hermes gateway

# أو كـ service: systemd على Linux / launchd على macOS
hermes gateway install
hermes gateway start
hermes gateway status

ℹ️

الشرح: الإعداد اليدوي في .env

لو مش عايز الـ wizard، احط نفس القيم في ملف ~/.hermes/.env — الـ token والمستخدمين المسموح لهم، وبينهم فاصلة.

bash — ~/.hermes/.env

TELEGRAM_BOT_TOKEN=123456789:ABCdefGHIjklMNOpqrSTUvwxYZ
TELEGRAM_ALLOWED_USERS=123456789    # فاصلة بين أكتر من مستخدم

🔒

القيمة الافتراضية آمنة

البوابة ترفض أي مستخدم مش موجود في الـ allowlist ومش عمل pairing. متحطش GATEWAY_ALLOW_ALL_USERS=true على بوت عنده صلاحية terminal أبداً.

Slide 5 — ديسكورد

إعداد Discord

السبب رقم واحد لفشل بوتات ديسكورد: الـ Intents

Privileged Intent	الغرض	مطلوب؟
`Server Members Intent`	يوصل لقائمة الأعضاء ويحلل الأسماء	✔ مطلوب
`Message Content Intent`	يقرأ نص الرسائل — بدونه النص فاضي	✔ مطلوب
`Presence Intent`	يشوف online / offline	اختياري

💡

الشرح: بعد تفعيل الـ Intents في الـ Developer Portal، احفظ التوكن وصدّره

من صفحة Bot في discord.com/developers/applications: اعمل Reset Token وانسخه، وفعّل Developer Mode عشان تنسخ الـ Server ID والـ User ID. ولازم تسمح للـ DMs من Privacy Settings وإلا البوت مش هيبعتلك pairing code.

bash

# صدّر التوكن بعد Reset Token من صفحة Bot
export DISCORD_BOT_TOKEN="YOUR_BOT_TOKEN"

# على Hermes: حدد المستخدمين المسموح لهم في .env
DISCORD_BOT_TOKEN=your-discord-bot-token
DISCORD_ALLOWED_USERS=123456789012345678

# على OpenClaw: رقّع الوكيل للguild مسموح وأقر أول pairing
openclaw config patch --file ./discord.patch.json5
openclaw pairing approve discord <CODE>

ℹ️

سلوك البوت في السيرفرات

في الـ DM بيجاوب على كل رسالة من غير mention. في قنوات السيرفر افتراضياً بيجاوب بس لما تعمله @mention. والـ threads معزولة عن القناة الأم في تاريخ الجلسة.

Slide 6 — سلاك

إعداد Slack

Socket Mode + manifest — مفيش URL عام

💡

الشرح: خلّي Hermes يولّد الـ manifest ليك

الأمر ده بيكتب ملف ~/.hermes/slack-manifest.json بالـ scopes والأحداث الصح، وبيطبع لك خطوات اللصق في api.slack.com/apps → Create New App → From an app manifest.

bash

# ولّد manifest جاهز بالـ scopes والأحداث
hermes slack manifest --agent-view --write

# على OpenClaw: ثبّت إضافة سلاك
openclaw plugins install @openclaw/slack

🚨

3 خطوات بتنسى — ودي سبب معظم المشاكل

1) الـ scopes مثل chat:write وchannels:history — 2) أحداث message.channels وapp_mention — 3) تفعيل Messages Tab في App Home، وبعدها Install to Workspace تاني.

ℹ️

الشرح: حط التوكنات في .env بعد التثبيت

بعد Install to Workspace انسخ Bot User OAuth Token (بيبدأ بـ xoxb-) و App-Level Token من Socket Mode (بيبدأ بـ xapp-)، زي كده:

bash — ~/.hermes/.env

SLACK_BOT_TOKEN=xoxb-y...here
SLACK_APP_TOKEN=xapp-your-app-token-here
SLACK_ALLOWED_USERS=U01ABC2DEF3          # Member IDs، فاصلة بين أكتر
# SLACK_HOME_CHANNEL=C01234567800     # القناة الافتراضية للـ cron

Slide 7 — واتساب بالـ QR

ربط WhatsApp بمسح QR

جسر Baileys — مفيش حساب Meta Developer ولا webhook عام

💡

الشرح: شغّل الأمر وامسح الـ QR اللي هيظهر في الـ terminal

الأمر ده بيفتح wizard يسألك الوضع (bot ولا self-chat)، يثبّت الـ bridge dependencies لو محتاج، يعرض الـ QR، ويستنى تدوس Scan. على الموبايل: Settings → Linked Devices → Link a Device ووجّه الكاميرا على الـ QR.

bash

# يعرض QR code في الـ terminal — امسحه من موبايلك
hermes whatsapp

# على OpenClaw: نفس الفكرة عبر login
openclaw plugins install @openclaw/whatsapp
openclaw channels add --channel whatsapp
openclaw channels login --channel whatsapp     # QR فقط
openclaw gateway

الخطوة اللي بعدها: تحكم في الوصول

bash — ~/.hermes/.env

WHATSAPP_ENABLED=true
WHATSAPP_MODE=bot                          # "bot" أو "self-chat"
WHATSAPP_ALLOWED_USERS=15551234567         # أرقام بمفتاح الدولة بدون +

⚠️

API غير رسمي — خطر حظر

واتساب ما يدعمش رسمياً بوتات طرف تالتة بره الـ Business API. استخدم رقم مخصص للبوت (مش رقمك الشخصي)، وماتبعتش رسايل جماعية ولا تعملش إرسال أوتوماتيك لناس مابدعتولهمش. الجلسة بتتحفظ في ~/.hermes/platforms/whatsapp/session وبتفضل بعد الـ restarts — بس ما تشاركهاش.

Slide 8 — سيجنال

إعداد Signal

أكثر تطبيقات المراسلة تركيزاً على الخصوصية

💡

الشرح: ثبّت signal-cli واربط حسابك كجهاز ثانوي

الآلية: Hermes بيتصل بـ Signal عن طريق signal-cli في وضع HTTP — الرسائل بتيجي عبر SSE والردود بتتبعت عبر JSON-RPC. على الموبايل: Settings → Linked Devices → Link New Device.

bash

# 1. ثبّت signal-cli — مش موجود في apt ولا snap، تحميل من GitHub
brew install signal-cli        # macOS

# 2. اربط حسابك — امسح الـ QR من موبايلك
signal-cli link -n "HermesAgent"

# 3. شغّل الـ daemon واتركه في الخلفية
signal-cli --account +123****7890 daemon --http 127.0.0.1:8080

# 4. اتأكد إنه شغال
curl http://127.0.0.1:8080/api/v1/check
# لازم يرجّع: {"versions":{"signal-cli":...}}

ℹ️

الشرح: اضبط Hermes على الـ daemon

اختار Signal في الـ wizard، أو حط الإعدادات يدوي. الـ SIGNAL_GROUP_ALLOWED_USERS لو اتظبطت = المجموعات مفتوحة، ولو سابتها فاضية = مقفولة.

bash — ~/.hermes/.env

SIGNAL_HTTP_URL=http://127.0.0.1:8080
SIGNAL_ACCOUNT=+123****7890

# أمني (موصى به)
SIGNAL_ALLOWED_USERS=+123****7890,+0987654321
SIGNAL_GROUP_ALLOWED_USERS=*        # * = يرد في أي مجموعة هو عضو فيها

Slide 9 — إدارة المجموعات

إدارة المحادثات الجماعية

ثلاث مفاهيم منفصلة — لا تخلطهم

💬

1. DM Access

مين يقدر يبعت رسالة مباشرة؟
allowFrom / *_ALLOWED_USERS

👥

2. Group Access

مين يقدر يحفّز البوت في المجموعات؟
groupPolicy + allowlists

🔔

3. Triggering

البوت يرد من غير ما تناديه؟
requireMention / /activation

المنصة	الافتراضي في المجموعات	إزاي يرد بدون mention
Telegram	يرد بس لو اتعمله mention أو / command	`require_mention: false` أو ارفعه admin
Discord	يرد بس عند @mention	`DISCORD_FREE_RESPONSE_CHANNELS`
Slack	يرد عند @mention	حدث `message.channels` + mention gating
WhatsApp	`pairing` — مش بيمرر خالص	`group_policy: open` + `WHATSAPP_REQUIRE_MENTION=false`
Signal	المجموعات مقفولة	`SIGNAL_GROUP_ALLOWED_USERS=*`

💡

نطاقات الصلاحيات

السؤال الأول «مين يوصل للبوت؟» بيتجاوب بالـ allowlist. السؤال التاني «هو داخل، إيه اللي مسموح يعمله؟» بيتجاوب بـ admin vs user — استخدم allow_admin_from و user_allowed_commands، واعرف مستواك بالأمر /whoami.

Slide 10 — استمرارية المحادثة

استمرارية المحادثة عبر المنصات

وكيل واحد بيتكلم معاك من أي منصة

Continuity — the same agent, three apps

Telegram: "اقرا الملف ده" → الوكيل بيقرأ Discord: "طيب، إيه اللي فيه؟" → الوكيل فاكر الملف WhatsApp: "ابعتلي summary" → بيبعت

🧠

OpenClaw — main session

مفتاح الجلسة agent:<agentId>:main — كل الـ DMs من كل المنصات بتتجمّع في محادثة واحدة دايرة.

🗃️

Hermes — session store

الجلسات بتتحدد بالـ origin (منصة + محادثة + مستخدم) — مفيش reset بالخمول ولا عند حد يومي.

💡

الشرح: وجّه رسالة بدون ما تولّد رد بالوكيل

الأوامر دي بتبعت رسالة مباشرة لأي قناة مهيّأة — مفيدة من سكريبتات الـ shell والـ cron والـ CI hooks، ومن غير أي تكلفة LLM. صيغة --to بتقبل platform أو platform:chat_id أو platform:#channel.

bash

# Hermes — ابعت لأي هدف مهيّأ
hermes send --to telegram "deploy finished"
hermes send --to discord:#ops --file /tmp/report.md
hermes send --list

# OpenClaw — نفس الفكرة
openclaw message send --channel telegram --target <chat-id> --message "deploy finished"

Slide 11 — الرسائل الصوتية

الرسائل الصوتية (STT / TTS)

فِرِّك الوارد، وولّد الرد الصوتي

🎙️

local

faster-whisper على جهازك — مفيش API key

⚡

groq

يتطلب GROQ_API_KEY — سريع جداً

🔑

openai

يتطلب VOICE_TOOLS_OPENAI_KEY

💡

الشرح: ثبّت ffmpeg عشان الصوت يوصل voice bubble

Edge TTS (الافتراضي المجاني) بيoutput MP3 ومحتاج ffmpeg للتحويل لـ Opus. من غيره الصوت بيبعت كملف صوتي عادي — لسه قابل للتشغيل بس مش voice bubble.

bash

# ثبّت ffmpeg للتحويل من MP3 إلى Opus
sudo apt install ffmpeg       # Ubuntu/Debian
brew install ffmpeg            # macOS

ℹ️

الشرح: تحكّم في الصوت من داخل الشات

الأمر /voice بيقلب الردود الصوتية، ويقدر ينضم لقناة صوتية في ديسكورد أو يطلع منها، ويقولك الحالة الحالية.

in-chat commands

            /voice on        # شغّل الردود الصوتية

/voice off       # أوقفها

/voice tts       # TTS بس

/voice join      # انضم لقناة صوتية في ديسكورد

/voice leave     # اطلع منها

/voice status    # الحالة الحالية

Slide 12 — البريد الإلكتروني

البريد عبر IMAP / SMTP

اللي عنده حساب حقيقي — مش bot token

البروتوكول	الوظيفة	المنفذ الافتراضي
`IMAP`	قراءة الرسائل من السيرفر	`993` (IMAP SSL)
`SMTP`	إرسال الردود	`587` (SMTP STARTTLS)

💡

الشرح: اعمل app password مش كلمة مرور حسابك

Gmail: فعّل 2FA ثم افتح myaccount.google.com/apppasswords. Outlook: فعّل 2FA واعمل App Password تحت Additional security options. استخدم الـ app password في الإعدادات دي.

bash — ~/.hermes/.env

# مطلوب
EMAIL_ADDRESS=hermes@gmail.com
EMAIL_PASSWORD=abcd efgh ijkl mnop    # App password — مش كلمة مرور حسابك
EMAIL_IMAP_HOST=imap.gmail.com
EMAIL_SMTP_HOST=smtp.gmail.com

# أمني (موصى به)
EMAIL_ALLOWED_USERS=your@email.com

# اختياري
EMAIL_POLL_INTERVAL=15                 # ثواني بين كل فحص للـ inbox

🚨

استخدم inbox مخصص — متستخدمش بريدك الشخصي

الإيمال أصعب في التحكم من الشات. الـ adapter بيشترط هيدر Authentication-Results اللي بيوثّق دومين المرسل (DMARC)، ويتجاهل المرسلين الآليين بصمت ويمنع reply loops. شغّل البوابة بالأمر ده:

bash

hermes gateway setup     # اختار Email
hermes gateway
hermes gateway install && hermes gateway start

Slide 13 — المقارنة

OpenClaw vs Hermes

على مستوى منصات المراسلة

العنصر	OpenClaw	Hermes Agent
اللغة	Node.js	Python
تثبيت القنوات	`openclaw plugins install @openclaw/<x>`	ضمن الـ installer
ملف الإعدادات	`~/.openclaw/openclaw.json` (JSON5)	`~/.hermes/config.yaml` + `.env`
Email (IMAP/SMTP)	✘ غير مدعوم	✔ مدعوم (hermes-email)
عدد المنصات	11+ قناة جاهزة	21 natively
استمرارية المحادثة	main session (كل الـ DMs)	session store + `/sessions`
Zalo / WeChat	✔ مدعوم	✘ غير مدعوم
Admin / User tiers	`commands.ownerAllowlist`	✔ allow_admin_from

💡

الشرح: شغّل البوابة وشوف كل القنوات

الأمرين دول هما أسرع طريقة تتأكد إن كل القنوات اتوصلت: واحد بيشغّل البوابة كـ service والتاني بيسألك عن حالة كل قناة.

bash

# OpenClaw
openclaw gateway install
openclaw channels status --probe
openclaw doctor

# Hermes
hermes gateway install && hermes gateway start
hermes gateway status
hermes doctor

Slide 14 — المشروع العملي

مساعد متعدد المنصات

اربط نفس الوكيل على 3 منصات واختبر استمرارية المحادثة

🚀

Project: Telegram + Discord + Email

الهدف: ثلاث منصات، نفس الوكيل

1️⃣

تيليجرام: أنشئ البوت، أضفه بـ channels add أو gateway setup، واقبل الـ pairing

2️⃣

ديسكورد: فعّل Message Content Intent وServer Members Intent الأول — من غيرهم البوت مش هيقرأ

3️⃣

الإيمال: اعمل Gmail مخصص، فعّل 2FA، وapp password — متستخدمش بريدك الشخصي أبداً

4️⃣

استمرارية المحادثة: على تيليجرام قول «احفظلي رقمي»، وبعدين على ديسكورد قول «فكرتني بالرقم» وشوف الرد. جرّب /sessions و/whoami

5️⃣

مجموعة + صوت: أضف البوت لمجموعة، اختبر إنه يرد بس عند mention، وفعّل /voice on وffmpeg

💡

نصيحة

لاحظ الفرق: OpenClaw بيجمع كل الـ DMs في الـ main session واحد (continuity حقيقي)، بينما Hermes بيخزّن حسب الـ origin. سجّل النتيجة في جدول وقارن.

Slide 15 — اختبار المعرفة

اختبار

اختبر نفسك — 5 أسئلة سريعة

اختبار الموديول 4

Score: 0/5

Q1: البوت online على تيليجرام وشغال في الـ DM، بس مش بيرد في مجموعة. عملت /setprivacy → OFF. إيه الخطوة الناقصة؟

تشيل البوت من المجموعة وتضيفه تاني

تعمل restart للبوابة

تعمل pairing تاني مع البوت

تغير الـ bot token

Q2: على Slack البوت شغال في الـ DMs تمام، بس ما بيوصلش أي رسالة في القنوات العامة. إيه السبب الأول؟

الـ token خلص

ناقص حدث message.channels في Event Subscriptions

محتاجة webhook بدل Socket Mode

محتاجة صلاحية admin في السيرفر

Q3: بوت ديسكورد online بس يستقبل الأحداث والنص فاضي تماماً. إيه الـ Intent الناقص؟

Presence Intent

Server Members Intent

Message Content Intent

Guild Slash Commands Intent

Q4: ليه Hermes يقدر يشتغل على Email (IMAP/SMTP) و OpenClaw لأ؟

لأن Gmail بيمنع API غير الرسمي

لأن الإيمال بطيء جداً

لأن الإيمال حساب حقيقي ومحتاج IMAP/SMTP، مش bot token — وHermes عامله adapter كامل بـ imaplib وsmtplib

لأن OpenClaw مبني على Node.js

Q5: فين بتتحكم في مين يقدر يبعت للوكيل في الـ DMs؟

groupPolicy في الـ config

requireMention

allowFrom أو *_ALLOWED_USERS

allow_admin_from