Gateway
فحوصات السلامة
دليل موجز للتحقق من اتصال القنوات دون تخمين.
فحوصات سريعة
openclaw status- ملخص محلي: إمكانية الوصول إلى Gateway ووضعه، وتلميح التحديث، وعمر مصادقة القناة المرتبطة، والجلسات + النشاط الأخير.openclaw status --all- تشخيص محلي كامل (للقراءة فقط، وملوّن، وآمن للصقه لأغراض تصحيح الأخطاء).openclaw status --deep- يطلب من Gateway قيد التشغيل إجراء فحص مباشر (healthمعprobe:true)، بما في ذلك فحوصات القنوات لكل حساب عند دعمها.openclaw status --usage- يعرض لقطات استخدام موفّر النموذج/الحصة.openclaw health- يطلب من Gateway قيد التشغيل لقطة حالته الصحية (عبر WS فقط؛ دون مقابس قنوات مباشرة من CLI).openclaw health --verbose(الاسم البديل--debug) - يفرض فحصًا صحيًا مباشرًا ويطبع تفاصيل اتصال Gateway.openclaw health --json- مخرجات لقطة الحالة الصحية القابلة للقراءة آليًا.- أرسل
/statusكأمر دردشة مستقل في أي قناة للحصول على رد بالحالة دون استدعاء الوكيل. - السجلات: تابع
/tmp/openclaw/openclaw-*.logورشّح حسبweb-heartbeatوweb-reconnectوweb-auto-replyوweb-inbound.
بالنسبة إلى Discord وموفّري الدردشة الآخرين، لا تعبّر صفوف الجلسات عن حيوية المقبس.
تقرأ openclaw sessions وGateway sessions.list وأداة الوكيل sessions_list
حالة المحادثة المخزنة. يمكن للموفّر إعادة الاتصال وإظهار حالة قناة سليمة
قبل إنشاء أي صف جلسة جديد. استخدم أوامر حالة القناة
والحالة الصحية أعلاه لإجراء فحوصات الاتصال المباشر.
تشخيصات معمّقة
- بيانات الاعتماد على القرص:
ls -l ~/.openclaw/credentials/whatsapp/<accountId>/creds.json(يجب أن يكون وقت التعديل حديثًا). - مخزن الجلسات:
ls -l ~/.openclaw/agents/<agentId>/agent/openclaw-agent.sqlite. يظهر عدد المستلمين والمستلمون الحديثون عبرstatus. - مسار إعادة الربط:
openclaw channels logout && openclaw channels login --verboseعند ظهور رموز الحالة 409-515 أوloggedOutفي السجلات. يُعاد تشغيل مسار تسجيل الدخول عبر رمز QR تلقائيًا مرة واحدة للحالة 515 بعد الاقتران. - تكون التشخيصات مفعّلة افتراضيًا (يعطّلها
diagnostics.enabled: false). تسجّل أحداث الذاكرة أعداد بايتات RSS/الكومة وضغط العتبة/النمو؛ ويُسجَّل ضغط الذاكرة الحرج عبر مسجّل Gateway، وعند تعيينdiagnostics.memoryPressureSnapshot: true، تُكتب أيضًا حزمة استقرار تسبق نفاد الذاكرة (إحصاءات كومة V8، وعدّادات Linux cgroup عند توفرها، وأعداد الموارد النشطة، وأكبر ملفات الجلسات/النصوص حسب المسار النسبي المنقّح). تسجّل تحذيرات الحيوية تأخر حلقة الأحداث/استخدامها، ونسبة أنوية CPU، وأعداد الجلسات النشطة/المنتظرة/الموجودة في قائمة الانتظار عندما تكون العملية قيد التشغيل لكنها مشبعة. تسجّل أحداث الحمولات الزائدة الحجم ما تم رفضه/اقتطاعه/تقسيمه إلى أجزاء، إلى جانب الأحجام والحدود، ولا تسجّل مطلقًا نص الرسالة أو محتويات المرفقات أو أجسام Webhook أو أجسام الطلبات/الاستجابات الخام أو الرموز المميزة أو ملفات تعريف الارتباط أو القيم السرية. - يقود Heartbeat نفسه مسجّل الاستقرار محدود الحجم:
openclaw gateway stability(أو استدعاء Gateway RPC diagnostics.stability). تحفظ حالات الخروج القاتلة لـ Gateway، وانتهاء مهلة إيقاف التشغيل، وفشل بدء التشغيل بعد إعادة التشغيل، وضغط الذاكرة الحرج (عندdiagnostics.memoryPressureSnapshot: true) أحدث لقطة ضمن~/.openclaw/logs/stability/. افحص أحدث حزمة باستخدامopenclaw gateway stability --bundle latest. - بالنسبة إلى تقارير الأخطاء، شغّل
openclaw gateway diagnostics exportوأرفق ملف zip المُنشأ: ملخص Markdown، وأحدث حزمة استقرار، وبيانات وصفية منقّحة للسجلات، ولقطات منقّحة لحالة Gateway وحالته الصحية، وشكل الإعدادات. تُحذف أو تُنقّح نصوص الدردشة وأجسام Webhook ومخرجات الأدوات وبيانات الاعتماد وملفات تعريف الارتباط ومعرّفات الحسابات/الرسائل والقيم السرية. راجع تصدير التشخيصات.
إعداد مراقب الحالة الصحية
gateway.channelHealthCheckMinutes: معدل فحص Gateway للحالة الصحية للقناة. القيمة الافتراضية:5. عيّن0لتعطيل عمليات إعادة التشغيل التي ينفذها مراقب الحالة الصحية عموميًا.gateway.channelStaleEventThresholdMinutes: المدة التي يمكن أن تظل فيها القناة المتصلة خاملة قبل أن يعدّها مراقب الحالة الصحية قديمة ويعيد تشغيلها. القيمة الافتراضية:30. أبقِ هذه القيمة أكبر من أو تساويgateway.channelHealthCheckMinutes.gateway.channelMaxRestartsPerHour: الحد الأقصى المتجدد خلال ساعة واحدة لعمليات إعادة التشغيل التي ينفذها مراقب الحالة الصحية لكل قناة/حساب. القيمة الافتراضية:10.channels.<provider>.healthMonitor.enabled: يعطّل عمليات إعادة التشغيل التي ينفذها مراقب الحالة الصحية لقناة محددة مع إبقاء المراقبة العامة مفعّلة.channels.<provider>.accounts.<accountId>.healthMonitor.enabled: تجاوز متعدد الحسابات تكون له الأولوية على الإعداد على مستوى القناة.- تنطبق هذه التجاوزات الخاصة بكل قناة على القنوات المضمّنة التي توفرها حاليًا: Discord وGoogle Chat وiMessage وIRC وMicrosoft Teams وSignal وSlack وTelegram وWhatsApp.
مراقبة وقت التشغيل
يجب أن تستخدم خدمات مراقبة وقت التشغيل الخارجية نقطة النهاية المخصصة /health، لا /v1/chat/completions.
- استخدم:
GET /health- استجابة فورية، دون إنشاء جلسة، ودون استدعاء LLM، ويُرجع{"ok":true,"status":"live"} - لا تستخدم:
/v1/chat/completionsلفحوصات الحالة الصحية - ينشئ كل طلب جلسة وكيل كاملة مع لقطة Skills وتجميع السياق واستدعاءات LLM
عند عدم توفير ترويسة x-openclaw-session-key أو حقل user، ينشئ /v1/chat/completions جلسة عشوائية جديدة لكل طلب. تنشئ خدمات المراقبة التي ترسل فحصًا كل 15 دقيقة نحو 96 جلسة/يوم، تستهلك كل منها 4-22KB. وبمرور الوقت، يؤدي هذا إلى تضخم مخزن الجلسات وقد يسبب تجاوز نافذة السياق.
أمثلة لإعداد خدمات المراقبة
- BetterStack: عيّن عنوان URL لفحص الحالة الصحية إلى
https://<your-gateway-host>:<port>/health - UptimeRobot: أضف مراقب HTTP جديدًا بعنوان URL
https://<your-gateway-host>:<port>/health - عام: يعيد أي طلب HTTP GET إلى
/healthالحالة 200 مع{"ok":true}عندما يكون Gateway سليمًا
عند حدوث عطل
logged outأو حالة 409-515 -> أعد الربط باستخدامopenclaw channels logoutثمopenclaw channels login.- يتعذر الوصول إلى Gateway -> شغّله:
openclaw gateway --port 18789(استخدم--forceإذا كان المنفذ مشغولًا). - لا توجد رسائل واردة -> تأكد من اتصال الهاتف المرتبط بالإنترنت ومن السماح للمرسل (
channels.whatsapp.allowFrom)؛ وبالنسبة إلى الدردشات الجماعية، تأكد من تطابق قائمة السماح + قواعد الإشارة (channels.whatsapp.groupsوagents.list[].groupChat.mentionPatterns).
أمر "health" المخصص
يطلب openclaw health من Gateway قيد التشغيل لقطة حالته الصحية (دون مقابس قنوات
مباشرة من CLI). ويُرجع افتراضيًا لقطة حديثة مخزنة مؤقتًا لـ Gateway،
ويحدّث Gateway ذاكرة التخزين المؤقت هذه في الخلفية؛ بينما يفرض --verbose فحصًا مباشرًا بدلًا من ذلك.
يبلغ الأمر عن عمر بيانات الاعتماد/المصادقة المرتبطة عند توفرها، وملخصات الفحص لكل قناة،
وملخص مخزن الجلسات، ومدة الفحص. وينتهي برمز غير صفري إذا تعذر
الوصول إلى Gateway أو فشل الفحص/انتهت مهلته.
الخيارات:
--json: مخرجات JSON قابلة للقراءة آليًا--timeout <ms>: يتجاوز مهلة الفحص الافتراضية البالغة 10s--verbose: يفرض فحصًا مباشرًا ويطبع تفاصيل اتصال Gateway--debug: اسم بديل لـ--verbose
تتضمن لقطة الحالة الصحية: ok (قيمة منطقية)، وts (طابع زمني)، وdurationMs (وقت الفحص)، وحالة كل قناة، وتوفر الوكيل، وملخص مخزن الجلسات.
