Telegram

تستخدم بوتات Telegram افتراضيًا Privacy Mode، مما يحد من رسائل المجموعة التي تتلقاها.

للاطلاع على جميع رسائل المجموعة، يمكنك إما:

• تعطيل وضع الخصوصية عبر /setprivacy، أو
• تعيين البوت مشرفًا على المجموعة.

بعد تبديل وضع الخصوصية، أزل البوت وأعد إضافته في كل مجموعة كي يطبق Telegram التغيير.

تُضبط حالة المشرف في إعدادات مجموعة Telegram. تتلقى البوتات المشرفة جميع رسائل المجموعة، وهو أمر مفيد للسلوك الدائم التشغيل في المجموعات.

• /setjoingroups — السماح بإضافة البوت إلى المجموعات أو منعها
• /setprivacy — سلوك إمكانية الظهور في المجموعات

تتوفر الإعدادات نفسها في تطبيق الويب الخاص بـ BotFather إذا كنت تفضّل واجهة مستخدم على أوامر الدردشة.

يبث OpenClaw الردود الجزئية في الوقت الفعلي ضمن المحادثات المباشرة والمجموعات والموضوعات: يرسل رسالة معاينة، ثم ينفّذ editMessageText مرارًا، ويُتمّها في موضعها.

• القيمة channels.telegram.streaming هي off | partial | block | progress (الافتراضي: partial)
• تُؤجَّل معاينات الإجابات الأولية القصيرة، ثم تُنشأ بعد مهلة محدودة إذا ظل التشغيل نشطًا
• يحتفظ progress بمسودة حالة واحدة قابلة للتحرير لتقدم الأدوات، ويعرض تسمية الحالة المستقرة عندما يصل نشاط الإجابة قبل تقدم الأداة، ويمحوها عند الاكتمال، ويرسل الإجابة النهائية كرسالة عادية
• يتحكم streaming.preview.toolProgress في ما إذا كانت تحديثات الأدوات/التقدم تعيد استخدام رسالة المعاينة المعدّلة نفسها (الافتراضي: true عندما يكون بث المعاينة نشطًا)
• يتحكم streaming.preview.commandText في تفاصيل الأوامر/التنفيذ ضمن تلك الأسطر: raw (الافتراضي) أو status (تسمية الأداة فقط)
• يتيح streaming.progress.commentary (الافتراضي: false) تضمين نص تعليق/تمهيد المساعد في مسودة التقدم المؤقتة
• تُكتشف القيم القديمة channels.telegram.streamMode، والقيم المنطقية لـ streaming، ومفاتيح معاينة المسودة الأصلية المتقاعدة؛ شغّل openclaw doctor --fix لترحيلها

أسطر تقدم الأدوات هي تحديثات الحالة القصيرة التي تظهر أثناء تشغيل الأدوات (تنفيذ الأوامر، وقراءة الملفات، وتحديثات التخطيط، وملخصات التصحيحات، وتمهيد/تعليق Codex في وضع خادم التطبيق). يُبقيها Telegram مفعّلة افتراضيًا (بما يطابق السلوك المنشور منذ v2026.4.22+).

أبقِ تعديلات معاينة الإجابة مع إخفاء أسطر تقدم الأدوات:

{  "channels": {    "telegram": {      "streaming": {        "mode": "partial",        "preview": { "toolProgress": false }      }    }  }}

أبقِ تقدم الأدوات ظاهرًا مع إخفاء نص الأوامر/التنفيذ:

{  "channels": {    "telegram": {      "streaming": {        "mode": "partial",        "preview": { "commandText": "status" }      }    }  }}

يعرض وضع progress تقدم الأدوات من دون تعديل الإجابة النهائية داخل تلك الرسالة. ضع سياسة نص الأوامر ضمن streaming.progress:

{  "channels": {    "telegram": {      "streaming": {        "mode": "progress",        "progress": {          "toolProgress": true,          "commandText": "status"        }      }    }  }}

يعطّل streaming.mode: "off" تعديلات المعاينة ويمنع رسائل الأدوات/التقدم العامة بدلًا من إرسالها كرسائل حالة مستقلة؛ وتظل مطالبات الموافقة والوسائط والأخطاء تمر عبر التسليم النهائي العادي. ويُبقي streaming.preview.toolProgress: false تعديلات معاينة الإجابة فقط.

بالنسبة إلى الردود النصية فقط: تتلقى المعاينات القصيرة التعديل النهائي في موضعها؛ وتعيد النتائج النهائية الطويلة التي تنقسم إلى رسائل متعددة استخدام المعاينة كالمقطع الأول، ثم ترسل الباقي فقط؛ وتمحو النتائج النهائية في وضع التقدم مسودة الحالة وتستخدم التسليم النهائي العادي؛ وإذا فشل التعديل النهائي قبل تأكيد الاكتمال، يعود OpenClaw إلى التسليم النهائي العادي وينظف المعاينة القديمة. وبالنسبة إلى الردود المعقدة (حُمولات الوسائط)، يعود OpenClaw دائمًا إلى التسليم النهائي العادي وينظف المعاينة.

بث المعاينة وبث الكتل متنافيان — فعندما يُفعَّل بث الكتل صراحةً، يتخطى OpenClaw بث المعاينة لتجنب البث المزدوج.

الاستدلال: يبث /reasoning stream الاستدلال إلى المعاينة المباشرة أثناء الإنشاء، ثم يحذف معاينة الاستدلال بعد التسليم النهائي (استخدم /reasoning on لإبقائها ظاهرة). وتُرسل الإجابة النهائية من دون نص الاستدلال.

يستخدم النص الصادر رسائل HTML القياسية في Telegram افتراضيًا، وهي قابلة للقراءة عبر العملاء الحاليين: نص عريض، ومائل، وروابط، وشيفرة، ومحتوى مخفي، واقتباسات — وليس كتل Bot API 10.2 الغنية فقط (الجداول الأصلية، والتفاصيل، والوسائط الغنية، والصيغ).

فعّل رسائل Bot API 10.2 الغنية:

{channels: {telegram: {  richMessages: true,},},}

عند التفعيل: يُبلَّغ الوكيل بأن الرسائل الغنية متاحة لهذا البوت/الحساب (مع عقد التأليف المدعوم باستخدام Markdown وجزر HTML)؛ ويُصيَّر نص Markdown عبر تمثيل Markdown الوسيط في OpenClaw إلى كتل غنية محددة الأنواع من Bot API 10.2 (العناوين، والجداول، والتفاصيل، وقوائم التحقق، والوسائط الغنية، والصيغ، والخرائط، والصور المجمعة)؛ وتظل تسميات الوسائط التوضيحية تستخدم تسميات HTML التوضيحية في Telegram (لا تحل الرسائل الغنية محل التسميات التوضيحية، ويبلغ حدها 1024 حرفًا).

يُبقي هذا نص النموذج بعيدًا عن رموز Markdown الغني في Telegram، بحيث لا تُفسَّر العملات مثل $400-600K على أنها تعبيرات رياضية. وينقسم النص الغني الطويل تلقائيًا وفق حدود Telegram. وتعود الجداول التي تتجاوز حد 20 عمودًا إلى كتلة شيفرة.

الافتراضي: معطّل، لضمان توافق العملاء — إذ تعرض بعض إصدارات عملاء Desktop وWeb وAndroid والعملاء الخارجيين الحالية الرسائل الغنية المقبولة على أنها غير مدعومة. أبقِ هذا الخيار معطّلًا ما لم يتمكن كل عميل مستخدم مع البوت من عرضها. يوضّح /status ما إذا كانت الرسائل الغنية مفعّلة أو معطّلة في الجلسة الحالية.

معاينات الروابط مفعّلة افتراضيًا. يعطّل channels.telegram.linkPreview: false الاكتشاف التلقائي للكيانات في النص الغني.

تُسجَّل قائمة أوامر Telegram عند بدء التشغيل باستخدام setMyCommands. ويفعّل commands.native: "auto" الأوامر الأصلية لـ Telegram.

أضف إدخالات أوامر مخصصة إلى القائمة:

{channels: {telegram: {  customCommands: [    { command: "backup", description: "نسخة Git احتياطية" },    { command: "generate", description: "إنشاء صورة" },  ],},},}

القواعد: تُطبَّع الأسماء (بإزالة / البادئة وتحويلها إلى أحرف صغيرة)؛ والنمط الصالح هو a-z و0-9 و_، والطول 1-32؛ ولا تستطيع الأوامر المخصصة تجاوز الأوامر الأصلية؛ وتُتخطى التعارضات/التكرارات وتُسجَّل.

الأوامر المخصصة مجرد إدخالات في القائمة — ولا تنفّذ السلوك تلقائيًا. ويمكن أن تظل أوامر Plugin/Skills تعمل عند كتابتها حتى إذا لم تظهر في قائمة Telegram. وإذا عُطّلت الأوامر الأصلية، تُزال الأوامر المضمّنة؛ وقد تظل أوامر Plugin/الأوامر المخصصة تُسجَّل إذا كانت مضبوطة.

إخفاقات الإعداد الشائعة:

• ظهور setMyCommands failed مع BOT_COMMANDS_TOO_MUCH بعد إعادة محاولة الاختصار يعني أن القائمة لا تزال تتجاوز الحد؛ قلّل أوامر Plugin/Skills/الأوامر المخصصة أو عطّل channels.telegram.commands.native.
• فشل deleteWebhook أو deleteMyCommands أو setMyCommands مع 404: Not Found بينما تعمل أوامر curl المباشرة لـ Bot API يعني عادةً أن channels.telegram.apiRoot ضُبط على نقطة نهاية /bot<TOKEN> الكاملة. يجب أن يكون apiRoot جذر Bot API فقط؛ ويزيل openclaw doctor --fix اللاحقة /bot<TOKEN> المضافة بالخطأ.
• يعني getMe returned 401 أن Telegram رفض رمز البوت المضبوط. حدّث botToken أو tokenFile أو TELEGRAM_BOT_TOKEN (الحساب الافتراضي) برمز BotFather الحالي؛ يتوقف OpenClaw قبل الاستطلاع، لذا لا يُبلَّغ عن ذلك كفشل في تنظيف Webhook.
• يشير setMyCommands failed المصحوب بأخطاء الشبكة/الجلب عادةً إلى حظر DNS/HTTPS الصادر إلى api.telegram.org.

أوامر إقران الأجهزة (Plugin ‏device-pair)

عند تثبيته:

1. ينشئ /pair رمز إعداد
2. ألصق الرمز في تطبيق iOS
3. يسرد /pair pending الطلبات المعلّقة (بما فيها الدور/النطاقات)
4. للموافقة: /pair approve <requestId> أو /pair approve (الطلب المعلّق الوحيد) أو /pair approve latest

إذا أعاد جهاز المحاولة بتفاصيل مصادقة متغيرة (الدور، أو النطاقات، أو المفتاح العام)، يُستبدل الطلب المعلّق السابق بطلب requestId جديد؛ أعد تشغيل /pair pending قبل الموافقة.

مزيد من التفاصيل: الإقران.

اضبط نطاق لوحة المفاتيح المضمّنة:

{channels: {telegram: {  capabilities: {    inlineButtons: "allowlist",  },},},}

تجاوز لكل حساب:

{channels: {telegram: {  accounts: {    main: {      capabilities: {        inlineButtons: "allowlist",      },    },  },},},}

النطاقات: off وdm وgroup وall وallowlist (الافتراضي). يرتبط capabilities: ["inlineButtons"] القديم بـ "all".

مثال لإجراء رسالة:

{action: "send",channel: "telegram",to: "123456789",message: "اختر خيارًا:",buttons: [[  { text: "نعم", callback_data: "yes" },  { text: "لا", callback_data: "no" },],[{ text: "إلغاء", callback_data: "cancel" }],],}

مثال لزر تطبيق مصغر:

{action: "send",channel: "telegram",to: "123456789",message: "افتح التطبيق:",presentation: {blocks: [  {    type: "buttons",    buttons: [{ label: "تشغيل", web_app: { url: "https://example.com/app" } }],  },],},}

لا تعمل أزرار web_app إلا في المحادثات الخاصة بين المستخدم والبوت.

تُمرَّر نقرات الاستدعاء التي لا تطالب بها أي معالِجات تفاعلية مسجّلة لـ plugin إلى الوكيل كنص: callback_data: <value>.

الإجراءات:

• sendMessage (to، content، وmediaUrl اختياري، وreplyToMessageId، وmessageThreadId)
• react (chatId، messageId، emoji)
• deleteMessage (chatId، messageId)
• editMessage (chatId، messageId، content أو caption، وأزرار presentation المضمّنة اختيارية؛ تحدّث التعديلات التي تقتصر على الأزرار ترميز الرد)
• createForumTopic (chatId، name، وiconColor اختياري، وiconCustomEmojiId)

الأسماء البديلة الميسّرة: send، react، delete، edit، sticker، sticker-search، topic-create.

التحكّم في الإتاحة: channels.telegram.actions.sendMessage، deleteMessage، reactions، sticker (الافتراضي: معطّل). تكون edit وcreateForumTopic وeditForumTopic مفعّلة افتراضيًا بلا مفتاح تبديل مخصّص. تستخدم عمليات الإرسال في وقت التشغيل لقطة الإعدادات/الأسرار النشطة منذ بدء التشغيل/إعادة التحميل، ولذلك لا تعيد مسارات الإجراءات تحليل قيم SecretRef عند كل إرسال.

دلالات إزالة التفاعلات: /tools/reactions.

وسوم تسلسل الردود الصريحة في المخرجات المنشأة:

• [[reply_to_current]] — يرد على الرسالة المشغِّلة
• [[reply_to:<id>]] — يرد على معرّف رسالة محدد

channels.telegram.replyToMode: off (الافتراضي)، first، all.

عند تمكين تسلسل الردود وتوفّر النص/التعليق الأصلي، يضيف OpenClaw مقتطف اقتباس أصليًا تلقائيًا. يقصر Telegram نص الاقتباس الأصلي على 1024 وحدة ترميز UTF-16؛ تُقتبس الرسائل الأطول من بدايتها، ويُرجع إلى رد عادي إذا رفض Telegram الاقتباس.

يعطّل off تسلسل الردود الضمني فقط؛ وتظل وسوم [[reply_to_*]] الصريحة مطبّقة.

مجموعات المنتدى الفائقة: تُلحق مفاتيح جلسات الموضوع :topic:<threadId>؛ وتستهدف الردود وحالة الكتابة سلسلة الموضوع؛ ومسار إعداد الموضوع هو channels.telegram.groups.<chatId>.topics.<threadId>.

الموضوع العام (threadId=1) حالة خاصة: تحذف عمليات إرسال الرسائل message_thread_id (يرفض Telegram القيمة sendMessage(...thread_id=1) برسالة "سلسلة المحادثة غير موجودة")، لكن إجراءات الكتابة تظل تتضمن message_thread_id (وهو مطلوب تجريبيًا لظهور مؤشر الكتابة).

ترث إدخالات الموضوع إعدادات المجموعة ما لم تُتجاوز (requireMention، allowFrom، skills، systemPrompt، enabled، groupPolicy). يقتصر agentId على الموضوع ولا يرث الإعدادات الافتراضية للمجموعة. يضبط topics."*" الإعدادات الافتراضية لكل موضوع في تلك المجموعة؛ وتظل معرّفات الموضوعات الدقيقة مقدّمة على "*".

توجيه الوكيل حسب الموضوع: يمكن توجيه كل موضوع إلى وكيل مختلف عبر agentId في إعداد الموضوع، ما يمنحه مساحة عمل وذاكرة وجلسة خاصة به:

{  channels: {    telegram: {      groups: {        "-1001234567890": {          topics: {            "1": { agentId: "main" },      // الموضوع العام -> الوكيل الرئيسي            "3": { agentId: "zu" },        // موضوع التطوير -> الوكيل zu            "5": { agentId: "coder" }      // مراجعة الشفرة -> الوكيل coder          }        }      }    }  }}

يصبح لكل موضوع حينئذٍ مفتاح جلسة خاص به، مثل agent:zu:telegram:group:-1001234567890:topic:3.

ربط موضوع ACP الدائم: يمكن لموضوعات المنتدى تثبيت جلسات حاضنة ACP عبر روابط مكتوبة من المستوى الأعلى (bindings[] مع type: "acp" وmatch.channel: "telegram" وpeer.kind: "group" ومعرّف مؤهل بموضوع مثل -1001234567890:topic:42). يقتصر النطاق حاليًا على موضوعات المنتدى في المجموعات/المجموعات الفائقة. راجع وكلاء ACP.

إنشاء ACP مرتبط بسلسلة من الدردشة: يربط /acp spawn <agent> --thread here|auto الموضوع الحالي بجلسة ACP جديدة؛ وتُوجّه المتابعات إليها مباشرةً، ويثبّت OpenClaw تأكيد الإنشاء داخل الموضوع. يتطلب channels.telegram.threadBindings.spawnSessions (الافتراضي: true).

يوفّر سياق القالب MessageThreadId وIsForum. تحتفظ محادثات الرسائل المباشرة التي تتضمن message_thread_id ببيانات الرد الوصفية، لكنها لا تستخدم مفاتيح جلسات تراعي سلاسل المحادثات إلا عندما يُبلغ getMe في Telegram عن has_topics_enabled: true. أزيل تجاوزا dm.threadReplies وdirect.*.threadReplies المتقاعدان؛ ويُعد وضع سلاسل المحادثات في BotFather المصدر الوحيد للحقيقة. شغّل openclaw doctor --fix لإزالة مفاتيح الإعداد القديمة.

الرسائل الصوتية

يميّز Telegram الملاحظات الصوتية عن الملفات الصوتية. الافتراضي: سلوك الملف الصوتي؛ ضع وسم [[audio_as_voice]] في رد الوكيل لفرض الإرسال كملاحظة صوتية. تُدرج نصوص الملاحظات الصوتية الواردة في سياق الوكيل بوصفها نصًا مولّدًا آليًا وغير موثوق، لكن اكتشاف الإشارات يظل يستخدم النص الخام، بحيث تستمر الرسائل الصوتية المشروطة بالإشارة في العمل.

{action: "send",channel: "telegram",to: "123456789",media: "https://example.com/voice.ogg",asVoice: true,}

رسائل الفيديو

يميّز Telegram ملفات الفيديو عن ملاحظات الفيديو. لا تدعم ملاحظات الفيديو التعليقات؛ ويُرسل نص الرسالة المقدّم بصورة منفصلة.

{action: "send",channel: "telegram",to: "123456789",media: "https://example.com/video.mp4",asVideoNote: true,}

المواقع والأماكن

استخدم إجراء send الحالي مع كائن location مستقل واحد. ترسل الإحداثيات دبوسًا أصليًا؛ وتؤدي إضافة كل من name وaddress إلى إرسال بطاقة مكان أصلية. لا يمكن دمج عمليات إرسال الموقع مع نص الرسالة أو الوسائط.

{action: "send",channel: "telegram",to: "123456789",location: {latitude: 48.858844,longitude: 2.294351,accuracy: 12,name: "برج إيفل",address: "شامب دي مارس، باريس",},}

الملصقات

الوارد: يُنزّل WEBP الثابت ويُعالج (العنصر النائب <media:sticker>)؛ ويُتخطى TGS المتحرك وWEBM للفيديو.

حقول سياق الملصق: Sticker.emoji، Sticker.setName، Sticker.fileId، Sticker.fileUniqueId، Sticker.cachedDescription. تُخزّن الأوصاف مؤقتًا في حالة plugin الخاصة بـ OpenClaw في SQLite لتقليل استدعاءات الرؤية المتكررة.

تمكين إجراءات الملصقات:

{channels: {telegram: {  actions: {    sticker: true,  },},},}

الإرسال:

{action: "sticker",channel: "telegram",to: "123456789",fileId: "CAACAgIAAxkBAAI...",}

البحث في الملصقات المخزنة مؤقتًا:

{action: "sticker-search",channel: "telegram",query: "قطة تلوّح",limit: 5,}

تصل تفاعلات Telegram كتحديثات message_reaction، منفصلة عن حمولات الرسائل. عند التمكين، يضع OpenClaw أحداث النظام مثل Telegram reaction added: 👍 by Alice (@alice) on msg 42 في قائمة الانتظار.

• channels.telegram.reactionNotifications: off | own | all (الافتراضي: own)
• channels.telegram.reactionLevel: off | ack | minimal | extensive (الافتراضي: minimal)

تعني own تفاعلات المستخدمين مع الرسائل التي أرسلها البوت فقط (بأفضل جهد عبر ذاكرة مؤقتة للرسائل المرسلة). تظل أحداث التفاعل خاضعة لعناصر تحكّم الوصول في Telegram (dmPolicy، allowFrom، groupPolicy، groupAllowFrom)؛ ويُستبعد المرسلون غير المصرح لهم.

لا يوفّر Telegram معرّفات سلاسل المحادثات في تحديثات التفاعل: تُوجّه المجموعات غير التابعة لمنتدى إلى جلسة محادثة المجموعة؛ وتُوجّه مجموعات المنتدى إلى جلسة الموضوع العام (:topic:1)، لا إلى الموضوع الأصلي الدقيق.

تتضمن allowed_updates للاستقصاء/Webhook القيمة message_reaction تلقائيًا.

يرسل ackReaction رمزًا تعبيريًا للإقرار أثناء معالجة OpenClaw لرسالة واردة. ويحدد messages.ackReactionScope متى يُرسل.

ترتيب تحديد الرمز التعبيري:

• channels.telegram.accounts.<accountId>.ackReaction
• channels.telegram.ackReaction
• messages.ackReaction
• الرجوع إلى الرمز التعبيري لهوية الوكيل (agents.list[].identity.emoji، وإلا "👀")

يتوقع Telegram رمزًا تعبيريًا من Unicode (مثل "👀")؛ استخدم "" لتعطيل التفاعل لقناة أو حساب.

النطاق (messages.ackReactionScope، الافتراضي "group-mentions"؛ لا يوجد حاليًا تجاوز على مستوى حساب Telegram أو قناة Telegram):

all (الرسائل المباشرة + المجموعات، بما فيها أحداث الغرف المحيطة)، direct (الرسائل المباشرة فقط)، group-all (كل رسالة جماعية باستثناء أحداث الغرف المحيطة، ولا رسائل مباشرة)، group-mentions (المجموعات عندما يُشار إلى البوت؛ لا رسائل مباشرة — الافتراضي)، off / none (معطّل).

تُفعّل كتابة إعدادات القناة افتراضيًا (configWrites !== false). تشمل عمليات الكتابة التي يشغّلها Telegram أحداث ترحيل المجموعة (migrate_to_chat_id، وتحديثات channels.telegram.groups) و/config set / /config unset (يتطلب تمكين الأوامر).

التعطيل:

{channels: {telegram: {  configWrites: false,},},}

الافتراضي هو الاستقصاء الطويل. لوضع Webhook، عيّن channels.telegram.webhookUrl وchannels.telegram.webhookSecret؛ ويمكن اختياريًا تعيين webhookPath (الافتراضي /telegram-webhook)، وwebhookHost (الافتراضي 127.0.0.1)، وwebhookPort (الافتراضي 8787)، وwebhookCertPath (شهادة PEM موقعة ذاتيًا لإعدادات عنوان IP المباشر أو بلا نطاق).

في وضع الاستقصاء الطويل، يحفظ OpenClaw علامة إعادة التشغيل المائية فقط بعد توزيع التحديث بنجاح؛ ويترك المعالِج الفاشل ذلك التحديث قابلًا لإعادة المحاولة في العملية نفسها بدلًا من وضع علامة اكتمال عليه.

يرتبط المستمع المحلي بـ 127.0.0.1:8787 افتراضيًا. للدخول العام، ضع وكيلًا عكسيًا أمام المنفذ المحلي، أو عيّن webhookHost: "0.0.0.0" عمدًا.

يتحقق وضع Webhook من حواجز الطلب ورمز Telegram السري ونص JSON، ثم يودع التحديث في قائمة انتظار الدخول الدائمة قبل إرجاع 200 فارغ. يتضمن التبنّي الدائم الناجح x-openclaw-delivery-accepted: durable؛ أما استجابات الصحة والتوجيه والمصادقة والتحقق وأخطاء التخزين فتحذف هذا الترويس. يمكن للوكلاء العكسيين ووحدات تحكّم المضيف اشتراط الترويس لتمييز تبنّي OpenClaw عن 200 فارغ عام دون استنتاج القبول من توقيت الاستجابة.

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

• channels.telegram.textChunkLimit القيمة الافتراضية 4000؛ يفضّل streaming.chunkMode="newline" حدود الفقرات (الأسطر الفارغة) قبل التقسيم حسب الطول.
• channels.telegram.mediaMaxMb (القيمة الافتراضية 100) يضع حدًا أقصى لحجم الوسائط الواردة والصادرة.
• channels.telegram.mediaGroupFlushMs (القيمة الافتراضية 500، والنطاق 10-60000) يتحكم في مدة تخزين الألبومات/مجموعات الوسائط مؤقتًا قبل أن يرسلها OpenClaw كرسالة واردة واحدة. زِده إذا وصلت أجزاء الألبوم متأخرة؛ وقلّله لتقليل زمن استجابة الرد على الألبوم.
• channels.telegram.timeoutSeconds يتجاوز مهلة عميل API (تُطبّق القيمة الافتراضية لـ grammY إذا لم يُضبط). تقيّد عملاء البوت القيم المضبوطة التي تقل عن حاجز طلب النص/الكتابة الصادر البالغ 60 ثانية، كي لا يُجهض grammY تسليم الرد المرئي قبل أن يتمكن حاجز النقل والمسار الاحتياطي في OpenClaw من العمل. يظل الاستقصاء الطويل يستخدم حاجز طلب getUpdates مدته 45 ثانية كي لا تُترك عمليات الاستقصاء الخاملة بلا نهاية.
• channels.telegram.pollingStallThresholdMs قيمته الافتراضية 120000؛ اضبطه بين 30000 و600000 فقط عند حدوث عمليات إعادة تشغيل بسبب اكتشاف خاطئ لتوقف الاستقصاء.
• يستخدم سجل سياق المجموعة channels.telegram.historyLimit أو messages.groupChat.historyLimit (القيمة الافتراضية 50)؛ ويؤدي 0 إلى تعطيله.
• يُطبّع السياق الإضافي للرد/الاقتباس/إعادة التوجيه في نافذة سياق محادثة واحدة محددة عندما يكون Gateway قد رصد الرسائل الأصلية؛ وتوجد ذاكرة التخزين المؤقت للرسائل المرصودة في حالة Plugin ضمن SQLite في OpenClaw، بينما يستورد openclaw doctor --fix الملفات الجانبية القديمة. لا يضمّن Telegram سوى reply_to_message سطحي واحد لكل تحديث، لذلك تقتصر السلاسل الأقدم من ذاكرة التخزين المؤقت على حمولة البيانات هذه.
• تتحكم قوائم السماح في Telegram أساسًا في مَن يمكنه تشغيل الوكيل، ولا تمثل حدًا كاملًا لتنقيح السياق الإضافي.
• سجل الرسائل المباشرة: channels.telegram.dmHistoryLimit، وchannels.telegram.dms["<user_id>"].historyLimit.
• ينطبق channels.telegram.retry على مساعدات الإرسال في Telegram (CLI/الأدوات/الإجراءات) لأخطاء API الصادرة القابلة للاسترداد. يستخدم تسليم الرد النهائي الوارد إعادة محاولة محدودة وآمنة للإرسال عند حالات الفشل السابقة للاتصال، لكنه لا يعيد محاولة أغلفة الشبكة الملتبسة بعد الإرسال، إذ قد تؤدي إلى تكرار الرسائل المرئية.

تقبل وجهات الإرسال في CLI وأداة الرسائل معرّف دردشة رقميًا أو اسم مستخدم أو وجهة موضوع منتدى:

openclaw message send --channel telegram --target 123456789 --message "مرحبًا"openclaw message send --channel telegram --target @name --message "مرحبًا"openclaw message send --channel telegram --target -1001234567890:topic:42 --message "مرحبًا بالموضوع"

تستخدم الاستطلاعات openclaw message poll وتدعم موضوعات المنتدى:

openclaw message poll --channel telegram --target 123456789 \--poll-question "هل ننشره؟" --poll-option "نعم" --poll-option "لا"openclaw message poll --channel telegram --target -1001234567890:topic:42 \--poll-question "اختر وقتًا" --poll-option "10 صباحًا" --poll-option "2 مساءً" \--poll-duration-seconds 300 --poll-public

أعلام الاستطلاع الخاصة بـ Telegram فقط: --poll-duration-seconds ‏(5-600)، و--poll-anonymous، و--poll-public، و--thread-id (أو وجهة :topic:). يكرر --poll-option من 2 إلى 12 مرة (الحد الأقصى لخيارات Telegram).

يدعم إرسال Telegram أيضًا --presentation مع كتل buttons للوحات المفاتيح المضمّنة (عندما يسمح channels.telegram.capabilities.inlineButtons بذلك)، و--pin أو --delivery '{"pin":true}' لطلب تسليم مثبّت عندما يستطيع البوت التثبيت في تلك الدردشة، و--force-document لإرسال الصور وملفات GIF ومقاطع الفيديو الصادرة كمستندات بدلًا من الرفع المضغوط/المتحرك/المرئي.

تقييد الإجراءات: يعطّل channels.telegram.actions.sendMessage=false جميع الرسائل الصادرة بما فيها الاستطلاعات؛ ويعطّل channels.telegram.actions.poll=false إنشاء الاستطلاعات مع إبقاء عمليات الإرسال العادية مفعّلة.

يدعم Telegram موافقات التنفيذ في الرسائل المباشرة للموافقين، ويمكنه اختياريًا نشر المطالبات في الدردشة أو الموضوع الأصلي. يجب أن تكون هوية الموافقين معرّفات مستخدمين رقمية في Telegram.

• channels.telegram.execApprovals.enabled (يُفعّل "auto" عند إمكانية التعرّف على موافق واحد على الأقل)
• channels.telegram.execApprovals.approvers (يرجع إلى معرّفات المالك الرقمية من commands.ownerAllowFrom)
• channels.telegram.execApprovals.target: ‏dm (الافتراضي) | channel | both
• agentFilter، وsessionFilter

تتحكم channels.telegram.allowFrom وgroupAllowFrom وdefaultTo في مَن يمكنه التحدث إلى البوت وفي موضع إرساله للردود العادية، لكنها لا تجعل أي شخص موافقًا على التنفيذ. يؤدي أول اقتران معتمد عبر رسالة مباشرة إلى تهيئة commands.ownerAllowFrom عندما لا يوجد مالك للأوامر بعد، بحيث تعمل إعدادات المالك الواحد دون تكرار المعرّفات ضمن execApprovals.approvers.

يعرض التسليم إلى القناة نص الأمر في الدردشة؛ لا تفعّل channel أو both إلا في المجموعات/الموضوعات الموثوقة. عندما تصل المطالبة إلى موضوع منتدى، يحافظ OpenClaw على الموضوع لمطالبة الموافقة والمتابعة. تنتهي صلاحية موافقات التنفيذ بعد 30 دقيقة افتراضيًا.

تتطلب أزرار الموافقة المضمّنة أيضًا أن يسمح channels.telegram.capabilities.inlineButtons بالواجهة المستهدفة (dm أو group أو all). تُحل معرّفات الموافقة التي تبدأ بالبادئة plugin: عبر موافقات Plugin؛ أما غيرها فتُحل أولًا عبر موافقات التنفيذ.

راجع موافقات التنفيذ.

• إذا كان requireMention=false، فيجب أن يسمح وضع الخصوصية في Telegram بالرؤية الكاملة: BotFather ‏/setprivacy -> Disable، ثم أزل البوت من المجموعة وأعد إضافته إليها.
• يحذّر openclaw channels status عندما تتوقع الإعدادات رسائل مجموعة بلا إشارة.
• يفحص openclaw channels status --probe معرّفات المجموعات الرقمية الصريحة؛ ولا يمكن فحص عضوية حرف البدل "*".
• اختبار سريع للجلسة: /activation always.

• عند وجود channels.telegram.groups، يجب إدراج المجموعة (أو تضمين "*").
• تحقق من عضوية البوت في المجموعة.
• راجع openclaw logs --follow لمعرفة أسباب التخطي.

• صرّح بهوية المرسل (الاقتران و/أو allowFrom الرقمي)؛ يظل تصريح الأوامر ساريًا حتى عندما تكون سياسة المجموعة open.
• يعني setMyCommands failed مع BOT_COMMANDS_TOO_MUCH أن القائمة الأصلية تحتوي على إدخالات أكثر من اللازم؛ قلّل أوامر Plugin أو Skills أو الأوامر المخصصة، أو عطّل القوائم الأصلية.
• تكون استدعاءات بدء التشغيل deleteMyCommands / setMyCommands واستدعاءات الكتابة sendChatAction محدودة، وتُعاد محاولتها مرة واحدة عبر مسار النقل الاحتياطي في Telegram عند انتهاء مهلة الطلب. تعني أخطاء الشبكة/الجلب المستمرة عادةً تعذّر الوصول عبر DNS/HTTPS إلى api.telegram.org.

• getMe returned 401 هو فشل مصادقة في Telegram لرمز البوت المضبوط. انسخ الرمز مجددًا أو أعد توليده في BotFather، ثم حدّث channels.telegram.botToken أو tokenFile أو accounts.<id>.botToken أو TELEGRAM_BOT_TOKEN (الحساب الافتراضي).
• يُعد deleteWebhook 401 Unauthorized أثناء بدء التشغيل فشل مصادقة أيضًا؛ فمعاملته باعتباره «لا يوجد Webhook» لن تؤدي إلا إلى تأجيل فشل الرمز غير الصالح نفسه حتى استدعاء API لاحق.

• يمكن أن يؤدي Node 22+ مع جلب/وكيل مخصص إلى سلوك إجهاض فوري إذا لم تتطابق أنواع AbortSignal.
• تحل بعض المضيفات api.telegram.org إلى IPv6 أولًا؛ ويتسبب خروج IPv6 المعطّل في حالات فشل متقطعة لـ API.
• تُعاد محاولة السجلات التي تحتوي على TypeError: fetch failed أو Network request for 'getUpdates' failed! باعتبارها أخطاء شبكة قابلة للاسترداد.
• أثناء بدء تشغيل الاستقصاء، يعيد OpenClaw استخدام فحص getMe الناجح عند بدء التشغيل لصالح grammY، كي لا يحتاج المشغّل إلى getMe ثانٍ قبل أول getUpdates.
• إذا فشل deleteWebhook بخطأ شبكة عابر أثناء بدء تشغيل الاستقصاء، ينتقل OpenClaw إلى الاستقصاء الطويل بدلًا من إجراء استدعاء آخر لمستوى التحكم قبل الاستقصاء. يظهر Webhook الذي لا يزال نشطًا عندئذٍ كتعارض getUpdates؛ ويعيد OpenClaw بناء النقل ويحاول تنظيف Webhook مجددًا.
• إذا أُعيد تدوير مقابس Telegram وفق وتيرة ثابتة قصيرة، فتحقق من انخفاض channels.telegram.timeoutSeconds؛ إذ تقيّد عملاء البوت القيم المضبوطة التي تقل عن حواجز الطلب الصادر وgetUpdates، لكن الإصدارات الأقدم كان يمكن أن تُجهض كل عملية استقصاء أو رد عند ضبطها دون تلك الحواجز.
• يعني Polling stall detected في السجلات أن OpenClaw يعيد تشغيل الاستقصاء ويعيد بناء النقل بعد مرور 120 ثانية دون اكتمال إثبات حيوية الاستقصاء الطويل افتراضيًا.
• يحذّر openclaw channels status --probe وopenclaw doctor عندما لا يكون حساب استقصاء قيد التشغيل قد أكمل getUpdates بعد مهلة بدء التشغيل، أو عندما لا يكون حساب Webhook قيد التشغيل قد أكمل setWebhook بعد مهلة بدء التشغيل، أو عندما يكون آخر نشاط ناجح لنقل الاستقصاء قديمًا.
• ارفع channels.telegram.pollingStallThresholdMs فقط عندما تكون استدعاءات getUpdates طويلة التشغيل سليمة، لكن مضيفك لا يزال يبلّغ عن عمليات إعادة تشغيل خاطئة بسبب توقف الاستقصاء. تشير حالات التوقف المستمرة عادةً إلى مشكلات في الوكيل أو DNS أو IPv6 أو خروج TLS إلى api.telegram.org.
• يراعي Telegram متغيرات بيئة وكيل العملية لنقل Bot API: ‏HTTP_PROXY وHTTPS_PROXY وALL_PROXY، وصيغها المكتوبة بأحرف صغيرة. لا يزال بإمكان NO_PROXY / no_proxy تجاوز api.telegram.org.
• إذا كان OPENCLAW_PROXY_URL مضبوطًا لبيئة خدمة ولا توجد متغيرات بيئة وكيل قياسية، يستخدم Telegram عنوان URL هذا لنقل Bot API أيضًا.
• على مضيفات VPS ذات خروج مباشر/TLS غير مستقر، وجّه استدعاءات Telegram API عبر وكيل:

channels:telegram:proxy: socks5://<user>:<password>@proxy-host:1080

• يستخدم Node 22+ افتراضيًا autoSelectFamily=true (باستثناء WSL2). يراعي ترتيب نتائج DNS في Telegram القيمة OPENCLAW_TELEGRAM_DNS_RESULT_ORDER، ثم channels.telegram.network.dnsResultOrder، ثم الإعداد الافتراضي للعملية (على سبيل المثال NODE_OPTIONS=--dns-result-order=ipv4first)؛ ويعود إلى ipv4first على Node 22+ إذا لم ينطبق أي منها.
• على WSL2، أو عندما يعمل السلوك المعتمد على IPv4 فقط بشكل أفضل، افرض تحديد العائلة:

channels:telegram:network:  autoSelectFamily: false

• إجابات نطاق قياس الأداء RFC 2544‏ (198.18.0.0/15) مسموح بها بالفعل افتراضيًا لتنزيل وسائط Telegram. إذا أعاد وكيل fake-IP موثوق أو وكيل شفاف كتابة api.telegram.org إلى عنوان خاص/داخلي/ذي استخدام خاص آخر أثناء تنزيل الوسائط، ففعّل التجاوز الخاص بـ Telegram فقط:

channels:telegram:network:  dangerouslyAllowPrivateNetwork: true

• يتوفر خيار التفعيل نفسه لكل حساب على حدة في channels.telegram.accounts.<accountId>.network.dangerouslyAllowPrivateNetwork.
• إذا كان وكيلك يحل أسماء مضيفي وسائط Telegram إلى 198.18.x.x، فاترك العلامة الخطرة معطلة أولًا — فهذا النطاق مسموح به بالفعل افتراضيًا.

• تجاوزات البيئة المؤقتة: OPENCLAW_TELEGRAM_DISABLE_AUTO_SELECT_FAMILY=1، OPENCLAW_TELEGRAM_ENABLE_AUTO_SELECT_FAMILY=1، OPENCLAW_TELEGRAM_DNS_RESULT_ORDER=ipv4first.
• تحقق من إجابات DNS:

dig +short api.telegram.org Adig +short api.telegram.org AAAA