إعداد وتشغيل OpenClaw: دليل المبتدئين لبناء بوتات تلجرام

الفصل الأول: مقدمة في OpenClaw وبيئة العمل

مرحباً بك في رحلتك نحو إتقان بناء بوتات تلجرام باستخدام OpenClaw. في هذا الفصل التأسيسي، سنغوص معاً في فهم ماهية هذا الإطار البرمجي القوي، ولماذا يُعد خياراً ممتازاً للمبتدئين والمحترفين على حد سواء، ثم سنقوم بإعداد بيئة التطوير المحلية الخاصة بك خطوة بخطوة. الهدف هو أن تنهي هذا الفصل وأنت تمتلك بيئة عمل جاهزة تماماً لبدء كتابة أول أسطر الكود الخاصة ببوتك.

ما هو OpenClaw؟

OpenClaw هو إطار عمل (Framework) مفتوح المصدر مكتوب بلغة JavaScript، مُصمم خصيصاً لتسهيل عملية تطوير بوتات تلجرام. يعمل كطبقة تجريد بينك وبين واجهة برمجة تطبيقات تلجرام (Bot API) المعقدة، ليقدم لك واجهة برمجة أبسط، أكثر تنظيماً، وأقرب إلى اللغة الطبيعية.

فكر فيه كـ "مساعد ذكي" يتولى المهام الروتينية والمعقدة نيابة عنك، مثل استقبال الرسائل من سيرفرات تلجرام، تحليلها، توجيهها للدالة الصحيحة، وإدارة الحالة (State) للمحادثات. هذا يترك لك، كمطور، التركيز على المنطق التطبيقي الفعلي لبوتك: ماذا يفعل عندما يرسل المستخدم أمراً معيناً؟ كيف يرد على الاستفسارات؟ كيف يتفاعل مع البيانات؟

المفاهيم الأساسية في OpenClaw

قبل أن نبدأ في التثبيت، من المهم أن تتعرف على بعض المصطلحات التي ستتردد كثيراً:

• الـ Bot Token: هو المفتاح السري الفريد الذي يعرف به تلجرام بوتك. تحصل عليه من @BotFather. يشبه "اسم المستخدم وكلمة المرور" لبوتك مجتمعة في سلسلة نصية.
• الـ Event Listener (مستمع الأحداث): هو دالة (Function) تقوم بتسجيلها في OpenClaw "تستمع" لحدوث حدث معين، مثل استقبال رسالة نصية (/start) أو ضغط على زر في لوحة المفاتيح. عند حدوث هذا الحدث، يتم تنفيذ الدالة.
• الـ Command Handler (معالج الأوامر): آلية داخل OpenClaw تقوم تلقائياً بمطابقة النص الذي أرسله المستخدم (مثل `/help`) مع الدالة المسؤولة عن معالجة هذا الأمر.
• الـ Context (السياق): كائن (Object) يحتوي على كل المعلومات المتعلقة بالحدث الحالي: محتوى الرسالة، بيانات المستخدم، معلومات الدردشة، وأدوات للرد (مثل `ctx.reply()`). يتم تمريره تلقائياً إلى دالة المستمع.

إعداد بيئة العمل خطوة بخطوة

الآن، لننتقل إلى الجزء العملي. سنقوم بإعداد مشروع Node.js جديد وتثبيت OpenClaw.

الخطوة 1: تثبيت Node.js و npm

تأكد من تثبيت Node.js (الإصدار 16 أو أحدث) على جهازك. افتح الطرفية (Terminal) أو سطر الأوامر (CMD/PowerShell) واكتب:

node --version
npm --version

إذا ظهر رقم الإصدار، فأنت جاهز. إذا لم يظهر، قم بتحميله وتثبيته من الموقع الرسمي nodejs.org.

الخطوة 2: إنشاء مشروع جديد وتهيئته

أنشئ مجلداً جديداً لمشروعك، وافتح الطرفية في هذا المجلد. ثم قم بتهيئة مشروع Node.js جديد:

npm init -y

سيؤدي هذا إلى إنشاء ملف `package.json` الذي يدير تبعيات (Dependencies) مشروعك.

الخطوة 3: تثبيت OpenClaw

الآن، حان وقت تثبيت حزمة OpenClaw نفسها. في الطرفية، قم بتنفيذ الأمر التالي:

npm install openclaw

سيقوم npm بتحميل مكتبة OpenClaw وجميع المكتبات التي تعتمد عليها، وتخزينها في مجلد `node_modules`.

الخطوة 4: الحصول على توكن البوت (Bot Token)

1. ابحث عن @BotFather في تطبيق تلجرام.
2. ابدأ محادثة جديدة واضغط على /start.
3. أرسل الأمر /newbot لإنشاء بوت جديد.
4. اتبع التعليمات: اختر اسمًا للبوت (مثل `MyTestBot`) ثم اسم المستخدم (يجب أن ينتهي بـ `bot`، مثل `my_test_123_bot`).
5. سيعطيك BotFather توكن الوصول. سيبدو هكذا:
1234567890:ABCdefGHIjklMNOpqrsTUVwxyz
6. احفظ هذا التوكن في مكان آمن ولا تشاركه أبداً. فهو يمثل بوتك، ومن يحصل عليه يمكنه التحكم به.

كتابة أول سطور الكود: "Hello World"

لنختبر أن كل شيء يعمل بشكل صحيح. قم بإنشاء ملف جديد في مجلد مشروعك وأسمه `index.js`. ثم افتحه وأضف الكود التالي:

// 1. استيراد مكتبة OpenClaw
const { OpenClaw } = require('openclaw');

// 2. إنشاء كائن (Instance) من البوت باستخدام التوكن الخاص بك
// استبدل 'YOUR_BOT_TOKEN' بالتوكن الذي حصلت عليه من BotFather
const bot = new OpenClaw('YOUR_BOT_TOKEN_HERE');

// 3. تعريف أول "مستمع حدث" (Event Listener)
// هذا المستمع سيتفاعل مع أمر /start فقط
bot.command('start', (ctx) => {
    // `ctx` هو كائن السياق الذي يحتوي على معلومات الرسالة والمستخدم
    // `ctx.reply()` هي الدالة المدمجة للرد على المستخدم في نفس الدردشة
    ctx.reply('مرحباً بالعالم! 🚀\nأهلاً بك في أول بوت لي باستخدام OpenClaw.');
});

// 4. تعريف مستمع آخر للأمر /help
bot.command('help', (ctx) => {
    ctx.reply('أنا بوت تجريبي. الأوامر المتاحة:\n/start - لبدء التشغيل\n/help - لعرض هذه الرسالة');
});

// 5. بدء تشغيل البوت وجعله يبدأ في استقبال التحديثات من تلجرام
bot.start();
console.log('✅ البوت يعمل الآن!...');

شرح الكود بالتفصيل

• السطر 1-2: نستورد المكتبة ثم ننشئ نسخة (Instance) فعلية من البوت. هذه النسخة هي قلب تطبيقك، وكل التفاعلات تتم من خلالها.
• السطر 8-15: نستخدم دالة `bot.command()` لتسجيل معالج أوامر. المعامل الأول هو نص الأمر (مثل `'start'`)، والمعامل الثاني هو دالة رد الاتصال (Callback Function) التي سيتم تنفيذها عندما يكتب المستخدم هذا الأمر. الدالة تأخذ معامل واحد هو `ctx` (السياق).
• دالة `ctx.reply()`: هذه هي الطريقة الأساسية للتواصل مع المستخدم. ترسل رسالة نصية إلى الدردشة التي جاء منها الأمر. تقبل OpenClaw خيارات أخرى لإرفاق لوحة مفاتيح أو تعديل التنسيق.
• السطر 23: `bot.start()` هي الدالة التي تشغل المحرك. عند تنفيذها، يبدأ البوت في الاتصال بخوادم تلجرام بشكل دوري (Long Polling) للتحقق من وجود رسائل أو أحداث جديدة، ثم يقوم بتوجيهها إلى المستمعين المناسبين.

الخطوة 5: تشغيل البوت

ارجع إلى الطرفية، وتأكد أنك في مجلد المشروع الذي يحتوي على ملف `index.js` وملف `package.json`. ثم قم بتنفيذ الأمر:

node index.js

إذا ظهرت الرسالة ✅ البوت يعمل الآن!... في الطرفية دون أخطاء، فهذا يعني أن البوت يعمل! اذهب الآن إلى تلجرام، وابحث عن اسم المستخدم الخاص ببوتك (مثل `my_test_123_bot`)، وأرسل له الأمر /start. يجب أن يرد عليك برسالة الترحيب "مرحباً بالعالم!".

الخلاصة والخطوات التالية

تهانينا! لقد نجحت في:
1. فهم فلسفة وأهمية إطار عمل OpenClaw.
2. إعداد بيئة تطوير Node.js كاملة.
3. الحصول على توكن بوت تلجرام فريد.
4. كتابة وتشغيل أول بوت تلجرام تفاعلي خاص بك.
لقد وضعت حجر الأساس. في الفصل القادم، سنتعمق أكثر في هيكلة المشروع بشكل احترافي، وتنظيم الأوامر والمعالجات، والتعامل مع أنواع مختلفة من المدخلات من المستخدم (نصوص، صور، أزرار). استمر في التجربة مع الأوامر `/start` و `/help`، وحاول إضافة أمر بسيط خاص بك، مثل `/about`، كتمرين قبل المتابعة.