تسجيل ومراقبة نشاط وكيلك في أوبن كلاو: تتبع كل خطوة
ما ستتعلمه: كيفية تفعيل السجلات المفصلة وتتبع نشاط وكيلك في أوبن كلاو، وكيفية قراءة البيانات التشخيصية لاكتشاف الأخطاء والاختناقات بسرعة.
المقدمة
وكيلك يعمل الآن. لكن ماذا يحدث بالفعل؟ هل ينفذ الخطوات كما تتوقع؟ هل هناك تأخير ما في مكان ما؟ هذه الأسئلة التي تطرحها عندما تدفع وكيلاً إلى بيئة الإنتاج لا يمكن الإجابة عليها بدون تسجيل ومراقبة جيدة.
مراقبة الوكيل في أوبن كلاو (OpenClaw) ليست خيارياً أو ترفاً. إنها ضرورة أساسية. عندما تستثمر الوقت والموارد في بناء وكيل ذكي، تحتاج إلى رؤية كاملة عن ما يفعله، أي الخطوات التي ينفذها، أين يستغرق الوقت، وأين تحدث الأخطاء. هذا الدليل سيعلمك كيفية القيام بذلك بشكل احترافي.
أساسيات التسجيل في أوبن كلاو
التسجيل في أوبن كلاو يعمل على مستويات متعددة. كل طبقة تعطيك معلومات مختلفة، من الرسائل العامة العالية المستوى إلى تفاصيل الاستدعاءات المنخفضة جداً.
أولاً، تحتاج إلى فهم أن التسجيل يحدث في موضعين: في الكود نفسه، وفي النظام الذي يشغل الوكيل. عندما تكتب وكيلاً يستخدم أدوات أو يتفاعل مع واجهات برمجية، كل هذه التفاعلات يمكن تسجيلها.
المستويات الأساسية للتسجيل هي:
- DEBUG: معلومات تفصيلية جداً. تستخدم عند التطوير لفهم سلوك الكود بالضبط.
- INFO: معلومات عامة عن تقدم الوكيل. تقول لك "بدأ الوكيل"، "وصل إلى الخطوة الثانية".
- WARNING: تنبيهات. شيء ما يحدث لكنه قد يكون مشكلة محتملة.
- ERROR: أخطاء. الوكيل لم يستطع إكمال ما كان يحاول فعله.
- CRITICAL: أخطاء حرجة تحقق توقف البرنامج.
إعداد التسجيل في وكيلك
إليك كيفية إعداد نظام تسجيل أساسي وفعال:
import logging
from datetime import datetime
# إنشاء logger
logger = logging.getLogger('openclaw_agent')
logger.setLevel(logging.DEBUG)
# معالج للملف
file_handler = logging.FileHandler(f'agent_logs_{datetime.now().strftime("%Y%m%d")}.log')
file_handler.setLevel(logging.DEBUG)
# معالج للطباعة على الشاشة
console_handler = logging.StreamHandler()
console_handler.setLevel(logging.INFO)
# صيغة التسجيل
formatter = logging.Formatter(
'%(asctime)s - %(name)s - %(levelname)s - %(message)s',
datefmt='%Y-%m-%d %H:%M:%S'
)
file_handler.setFormatter(formatter)
console_handler.setFormatter(formatter)
logger.addHandler(file_handler)
logger.addHandler(console_handler)
# الآن يمكنك استخدامه
logger.info('بدء الوكيل')
logger.debug('القيمة المدخلة: test_value')
logger.warning('هذه استدعاءة بطيئة للخدمة الخارجية')
logger.error('فشل الاتصال بقاعدة البيانات')
هذا الإعداد ينشئ ملف سجل يومي ويطبع الرسائل المهمة على الشاشة. كل رسالة تحتوي على التاريخ والوقت ومستوى الخطورة والرسالة نفسها.
تتبع خطوات الوكيل بالتفصيل
تسجيل الرسائل العامة ليس كافياً. تحتاج إلى تتبع كل خطوة، كل قرار، كل استدعاء خارجي. هذا يعني أن تكتب رسائل تسجيل في نقاط حرجة في الكود.
def process_user_request(request_id, user_input):
logger.info(f'معالجة الطلب {request_id}')
logger.debug(f'المدخل من المستخدم: {user_input}')
try:
# خطوة 1: تحليل المدخل
logger.info('خطوة 1: تحليل المدخل')
parsed = parse_input(user_input)
logger.debug(f'النتيجة المحللة: {parsed}')
# خطوة 2: استدعاء الأداة
logger.info('خطوة 2: استدعاء الأداة الخارجية')
start_time = datetime.now()
result = call_external_tool(parsed)
elapsed = (datetime.now() - start_time).total_seconds()
logger.debug(f'وقت التنفيذ: {elapsed} ثانية')
logger.debug(f'نتيجة الأداة: {result}')
# خطوة 3: معالجة النتيجة
logger.info('خطوة 3: معالجة النتيجة')
response = format_response(result)
logger.debug(f'الرد النهائي: {response}')
logger.info(f'انتهى الطلب {request_id} بنجاح')
return response
except Exception as e:
logger.error(f'خطأ في معالجة الطلب {request_id}: {str(e)}', exc_info=True)
raise
لاحظ أننا نسجل قبل وبعد كل عملية مهمة. نسجل المدخلات والمخرجات. نقيس الأوقات. نسجل الأخطاء مع التفاصيل الكاملة.
أنواع السجلات وماذا تسجل
| نوع السجل | ما يجب تسجيله | مثال | الأهمية |
|---|---|---|---|
| بدء العملية | معرف فريد، المدخلات الأساسية | "بدء معالجة الطلب #5432" | تتبع مسار العملية |
| استدعاء خارجي | اسم الخدمة، المعاملات، الوقت | "استدعاء API Google Sheets، المعامل: sheet_id=abc123" | تحديد الاختناقات |
| قرار منطقي | الشرط والنتيجة | "التحقق من الصلاحيات: مرفوض" | فهم السلوك |
| خطأ | رسالة الخطأ، السياق الكامل | "خطأ: قاعدة البيانات لا ترد (timeout بعد 30 ثانية)" | حل المشاكل |
| نهاية العملية | النتيجة النهائية، الوقت الكلي | "انتهت العملية بنجاح، الوقت الكلي: 2.3 ثانية" | التحقق من الأداء |
المراقبة في الوقت الفعلي
تسجيل الأحداث في ملفات ممل. أنت تريد أن ترى ما يحدث الآن. لهذا تحتاج إلى لوحة تحكم.
إذا كان وكيلك يعمل على خادم، يمكنك استخدام أداة مثل ELK (Elasticsearch, Logstash, Kibana) أو Datadog أو حتى حل بسيط مثل Splunk. لكن إن كنت تبدأ للتو، يمكنك استخدام حل أبسط.
أداة سهلة جداً هي نقل السجلات إلى سجل مركزي يمكنك البحث فيه. مثلاً:
import json
from datetime import datetime
class CentralizedLogger:
def __init__(self, agent_id):
self.agent_id = agent_id
self.logs = []
def log(self, level, message, data=None):
log_entry = {
'timestamp': datetime.now().isoformat(),
'agent_id': self.agent_id,
'level': level,
'message': message,
'data': data or {}
}
self.logs.append(log_entry)
# يمكنك إرسال هذا إلى قاعدة بيانات أو خدمة مراقبة
self.send_to_monitoring_service(log_entry)
def send_to_monitoring_service(self, entry):
# مثال: إرسال إلى MongoDB أو قاعدة بيانات أخرى
pass
# الاستخدام
logger = CentralizedLogger(agent_id='agent_001')
logger.log('INFO', 'بدء المعالجة', {'request_id': '5432', 'user': 'ahmed'})
هذا يسمح لك بالبحث عن جميع الأحداث لوكيل معين، في نطاق زمني معين، برسالة معينة. بكثير أفضل من البحث في ملف سجل نصي.
سيناريو عملي: تتبع خطأ حقيقي
تخيل أن لديك وكيلاً اسمه "مساعد الفواتير الذكي" يعمل 24/7 ويقرأ رسائل البريد الإلكتروني ويستخرج معلومات الفاتورة ويسجلها في جدول Sheet.
المشكلة: الوكيل يتوقف أحياناً في منتصف الليل. ثم يبدأ تلقائياً مرة أخرى. فواتير تُفقد.
الحل - الخطوة 1: تفعيل التسجيل المفصل
أضفنا سجلات في كل خطوة:
def invoice_assistant():
logger.info('بدء مساعد الفواتير')
while True:
try:
logger.info('بحث عن رسائل بريد جديدة')
emails = fetch_emails()
logger.debug(f'وجدت {len(emails)} رسالة')
for email in emails:
logger.info(f'معالجة البريد من {email.sender}')
try:
logger.debug(f'استخراج المرفقات...')
attachments = extract_attachments(email)
logger.debug(f'عدد المرفقات: {len(attachments)}')
for att in attachments:
logger.debug(f'تحليل الملف: {att.filename}')
invoice_data = parse_invoice(att)
logger.debug(f'البيانات المستخرجة: {invoice_data}')
logger.info(f'حفظ الفاتورة في Sheet')
save_to_sheet(invoice_data)
logger.info(f'تم حفظ الفاتورة بنجاح')
except Exception as e:
logger.error(f'خطأ في معالجة البريد: {str(e)}', exc_info=True)
continue
logger.info('انتهت الدورة، الانتظار 5 دقائق')
time.sleep(300)
except Exception as e:
logger.critical(f'خطأ حرج في المساعد: {str(e)}', exc_info=True)
logger.info('إعادة التشغيل خلال 60 ثانية')
time.sleep(60)
الخطوة 2: قراءة السجلات والبحث عن النمط
بعد أسبوع، بحثنا في السجلات عن كل مرة حدث فيها خطأ حرج:
2024-01-15 02:34:22 - ERROR - timeout connecting to Google Sheets API
2024-01-15 02:35:00 - CRITICAL - Critical error in assistant: ...
2024-01-15 02:35:60 - INFO - Restarting in 60 seconds
2024-01-16 03:12:15 - ERROR - timeout connecting to Google Sheets API
2024-01-16 03:13:00 - CRITICAL - Critical error in assistant: ...
الخطوة 3: تحديد السبب
النمط واضح: جميع الأخطاء الحرجة سببها timeout مع Google Sheets في ساعات الليل. ربما Google عندها صيانة دورية أو حد أقصى للطلبات.
الخطوة 4: التصحيح
أضفنا retry logic ومهلة انتظار أطول:
def save_to_sheet_with_retry(data, max_retries=3):
for attempt in range(max_retries):
try:
logger.debug(f'محاولة حفظ البيانات (محاولة {attempt + 1}/{max_retries})')
result = save_to_sheet(data)
logger.info(f'تم الحفظ بنجاح')
return result
except TimeoutError as e:
logger.warning(f'timeout في المحاولة {attempt + 1}، انتظار 30 ثانية...')
time.sleep(30)
if attempt == max_retries - 1:
logger.error(f'فشلت جميع المحاولات: {str(e)}')
raise
النتيجة: الآن الوكيل يعاد المحاولة تلقائياً بدل التوقف. السجلات تظهر "انتظار 30 ثانية" والفواتير تُحفظ بنجاح بعد ذلك.
بدون التسجيل المفصل، كان سيأخذ أسابيع لنكتشف أن المشكلة في timeout مع Google Sheets.
أسئلة شائعة
سؤال 1: كيف أتجنب أن يصبح ملف السجل كبيراً جداً؟
الجواب: استخدم rotation للملفات. بدلاً من كتابة كل شيء في ملف واحد، أنشئ ملف جديد كل يوم أو كل 100 ميغابايت. Python توفر RotatingFileHandler لهذا الغرض. مثلاً: RotatingFileHandler('agent.log', maxBytes=10*1024*1024, backupCount=10) ينشئ ملف جديد عندما يصل إلى 10 ميغابايت ويحتفظ بـ 10 ملفات قديمة.
سؤال 2: هل يبطئ التسجيل المفصل الوكيل؟
الجواب: نعم، قليلاً. لكن ببطء معقول جداً. تسجيل سطر واحد يأخذ أقل من ميلي ثانية. المشكلة الحقيقية تحدث عندما تكتب السجلات إلى قرص صلب ببطء أو إلى شبكة بطيئة. للحصول على أداء أفضل، استخدم queue: السجلات تدخل طابور، وخيط منفصل يكتبها. بهذا لا ينتظر الوكيل الرئيسي.
سؤال 3: هل يجب تسجيل المعلومات الحساسة مثل كلمات المرور والمفاتيح؟
الجواب: لا أبداً. لا تسجل كلمات المرور أو مفاتيح API أو أرقام بطاقات الائتمان. حتى لو سجلت، امسح السجلات القديمة بانتظام. إذا كنت تحتاج لتسجيل معرّف، سجل أول 4 أحرف فقط أو استخدم hash. التسجيل يجب أن يساعدك، ليس يعرّض البيانات الحساسة.
سؤال 4: كيف أفهم السجلات إذا كان الوكيل معقداً بكثير؟
الجواب: أضف معرّفات فريدة (correlation IDs). كل طلب يحصل على معرّف عند البداية، وكل سطر سجل يتضمن هذا المعرّف. هكذا تستطيع البحث عن معرّف واحد وترى كل شيء حدث في هذا الطلب بالترتيب الزمني. معرّفات مثل UUID أو حتى timestamp مع رقم عشوائي يكفي.
سؤال 5: ما الفرق بين logging والmonitoring؟
الجواب: Logging يسجل الأحداث في الملفات أو قاعدة بيانات. Monitoring يراقب المقاييس في الوقت الفعلي: عدد الطلبات في الثانية، متوسط الوقت، معدل الأخطاء. يمكنك أن تحذر تلقائياً إذا معدل الأخطاء تجاوز 5%. Logging هو "ماذا حدث"، Monitoring هو "كيف يعمل النظام الآن". تحتاج كليهما معاً. إذا أردت حلاً بسيطاً، ألقِ نظرة على دليل الأمان والخصوصية لأنه يتطرق إلى تخزين البيانات الآمن.
الخلاصة
تسجيل ومراقبة الوكيل ليست ترف. إنها الطريقة الوحيدة لفهم ما يحدث بالفعل عندما يعمل الوكيل بدون إشراف. بدون السجلات، أنت تخبط عشوائياً عند حل المشاكل.
ابدأ بإعداد بسيط: سجل الرسائل إلى ملف، مع مستويات أولويات واضحة. أضف معرّفات فريدة لكل عملية. سجل المدخلات والمخرجات لكل خطوة مهمة. قس الأوقات. عندما تنمو احتياجاتك، انتقل إلى حل مركزي أكثر قوة.
إذا كنت تريد حلاً جاهزاً بدون إنشاء كل هذا من الصفر، فارس، المساعد الذكي العربي على تيليجرام مبني بالفعل مع نظام مراقبة شامل. لكن فهم كيفية عمل التسجيل سيعلمك الكثير حتى لو استخدمت حلاً جاهزاً.
للمزيد حول بناء وكلاء قوية، اطلع على دليل المبتدئين لأوبن كلاو واختيار النموذج المناسب في أوبن كلاو.
إذا كان الوكيل يتفاعل مع جهات خارجية، اقرأ أيضاً أتمتة واتساب مع أوبن كلاو لرؤية نمط متكامل.
ابدأ الآن: افتح محرر الأكواد، أضف logger واحد، وسجل رسالة واحدة. بعدها الباقي سهل.
للمعلومات الفنية الأعمق حول أوبن كلاو، زر openclaw.ai.
جاهز لتجربة OpenClaw؟
ابدأ الآن مع دليل التثبيت الكامل بالعربية وابنِ أول وكيل ذكاء اصطناعي خاص بك.
دليل التثبيتمقالات ذات صلة
وكيل التسعير الذكي للتجارة الإلكترونية: تحسين الأسعار تلقائياً
وكيل التسعير الذكي للتجارة الإلكترونية مع أوبن كلاو: راقب أسعار المنافسين وعدّل أسعار متجرك تلقائياً ضمن قواعد حماية واضحة تحفظ هامش ربحك.
اقرأ المزيددمج التحويل الصوتي TTS وSTT في أوبن كلاو: وكيلك يتكلم ويسمع بالعربية
تعلّم دمج التحويل الصوتي TTS وSTT في أوبن كلاو خطوة بخطوة ليتكلم وكيلك ويسمع بالعربية، مع إعدادات حقيقية جاهزة ومقارنة بين المزودين ونصائح عملية لتيليغرام.
اقرأ المزيدأتمتة مطابع الطباعة مع أوبن كلاو: الطلبات والعروض ومتابعة التسليم
دليل عملي لأتمتة مطابع الطباعة مع أوبن كلاو: استقبال الطلبات من واتساب، تجهيز عروض الأسعار من جدولك، ومتابعة التسليم بمهام مجدولة وسيناريو تطبيقي كامل.
اقرأ المزيد