Gateway
فحوصات الصحة
دليل قصير للتحقق من اتصال القنوات دون تخمين.
فحوصات سريعة
openclaw status— ملخص محلي: قابلية الوصول إلى Gateway/الوضع، تلميح التحديث، عمر مصادقة القناة المرتبطة، الجلسات + النشاط الحديث.openclaw status --all— تشخيص محلي كامل (للقراءة فقط، ملوّن، آمن للصقه لأغراض التصحيح).openclaw status --deep— يطلب من Gateway العامل فحص سلامة مباشرًا (healthمعprobe:true)، بما في ذلك فحوصات القنوات لكل حساب عند دعمها.openclaw health— يطلب من Gateway العامل لقطة سلامته (عبر WS فقط؛ لا توجد مقابس قنوات مباشرة من CLI).openclaw health --verbose— يفرض فحص سلامة مباشرًا ويطبع تفاصيل اتصال Gateway.openclaw health --json— مخرجات لقطة سلامة قابلة للقراءة آليًا.- أرسل
/statusكرسالة مستقلة في WhatsApp/WebChat للحصول على رد حالة دون استدعاء الوكيل. - السجلات: تابع
/tmp/openclaw/openclaw-*.logوصفِّ حسبweb-heartbeatوweb-reconnectوweb-auto-replyوweb-inbound.
بالنسبة إلى Discord وموفري الدردشة الآخرين، لا تمثل صفوف الجلسات حيوية المقبس.
تقرأ openclaw sessions وsessions.list في Gateway وأداة الوكيل sessions_list
حالة المحادثة المخزنة. يمكن للموفر إعادة الاتصال وإظهار حالة قناة سليمة
قبل أن يتحقق أي صف جلسة جديد. استخدم أوامر حالة القناة والسلامة أعلاه لفحوصات الاتصال المباشر.
تشخيصات عميقة
- بيانات الاعتماد على القرص:
ls -l ~/.openclaw/credentials/whatsapp/<accountId>/creds.json(ينبغي أن يكون mtime حديثًا). - مخزن الجلسات:
ls -l ~/.openclaw/agents/<agentId>/sessions/sessions.json(يمكن تجاوز المسار في الإعدادات). يعرضstatusالعدد والمستلمين الحديثين. - مسار إعادة الربط:
openclaw channels logout && openclaw channels login --verboseعند ظهور رموز الحالة 409–515 أوloggedOutفي السجلات. (ملاحظة: يعيد مسار تسجيل الدخول عبر رمز QR التشغيل تلقائيًا مرة واحدة للحالة 515 بعد الاقتران.) - التشخيصات مفعّلة افتراضيًا. يسجل Gateway الحقائق التشغيلية ما لم يتم ضبط
diagnostics.enabled: false. تسجل أحداث الذاكرة عدد بايتات RSS/heap، وضغط العتبة، وضغط النمو. تُسجَّل ضغوط الذاكرة الحرجة عبر مسجل Gateway. عند ضبطdiagnostics.memoryPressureSnapshot: true، تكتب ضغوط الذاكرة الحرجة أيضًا حزمة استقرار قبل نفاد الذاكرة تتضمن إحصاءات V8 heap، وعدّادات Linux cgroup عند توفرها، وعدد الموارد النشطة، وأكبر ملفات الجلسات/النصوص حسب المسار النسبي المنقح. تسجل تحذيرات الحيوية تأخير حلقة الأحداث، واستخدام حلقة الأحداث، ونسبة أنوية CPU، وأعداد الجلسات النشطة/المنتظرة/المصفوفة عندما تكون العملية عاملة لكنها مشبعة. تسجل أحداث الحمولة الزائدة ما تم رفضه أو اقتطاعه أو تقسيمه، إضافة إلى الأحجام والحدود عند توفرها. لا تسجل نص الرسالة، أو محتويات المرفقات، أو جسم Webhook، أو جسم الطلب أو الاستجابة الخام، أو الرموز، أو ملفات تعريف الارتباط، أو القيم السرية. يبدأ Heartbeat نفسه مسجل الاستقرار المحدود، والمتاح عبرopenclaw gateway stabilityأو RPC diagnostics.stabilityفي Gateway. تحتفظ مخارج Gateway الفادحة، ومهل إيقاف التشغيل، وفشل بدء التشغيل بعد إعادة التشغيل بأحدث لقطة للمسجل تحت~/.openclaw/logs/stability/عند وجود أحداث؛ وتفعل ضغوط الذاكرة الحرجة ذلك أيضًا فقط عند ضبطdiagnostics.memoryPressureSnapshot: true. افحص أحدث حزمة محفوظة باستخدام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 وMicrosoft Teams وSignal وSlack وTelegram وWhatsApp.
مراقبة وقت التشغيل
ينبغي لخدمات مراقبة وقت التشغيل الخارجية استخدام نقطة النهاية المخصصة /health، وليس /v1/chat/completions.
- استخدم:
GET /health— استجابة فورية، لا تُنشأ جلسة، لا توجد مكالمة LLM، يعيد{"ok":true,"status":"live"} - لا تستخدم:
/v1/chat/completionsلفحوصات السلامة — ينشئ كل طلب جلسة وكيل كاملة مع لقطة skill، وتجميع السياق، ومكالمات 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 تلك الذاكرة المخبأة في الخلفية. يفرض openclaw health --verbose
فحصًا مباشرًا بدلًا من ذلك. يبلّغ الأمر عن بيانات الاعتماد المرتبطة/عمر المصادقة عند توفرها،
وملخصات فحص لكل قناة، وملخص مخزن الجلسات، ومدة الفحص. يخرج
برمز غير صفري إذا تعذر الوصول إلى Gateway أو فشل الفحص/انتهت مهلته.
الخيارات:
--json: مخرجات JSON قابلة للقراءة آليًا--timeout <ms>: تجاوز مهلة الفحص الافتراضية البالغة 10 ثوانٍ--verbose: فرض فحص مباشر وطباعة تفاصيل اتصال Gateway--debug: اسم بديل لـ--verbose
تتضمن لقطة السلامة: ok (قيمة منطقية)، وts (طابع زمني)، وdurationMs (وقت الفحص)، وحالة كل قناة، وتوفر الوكيل، وملخص مخزن الجلسات.
