Telegram

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

إذا كان يجب أن يرى الروبوت كل رسائل المجموعة، فإما أن:

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

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

تُدار حالة المشرف من إعدادات مجموعة Telegram.

تتلقى الروبوتات المشرفة كل رسائل المجموعة، وهذا مفيد لسلوك المجموعة الدائم التشغيل.

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

يستطيع OpenClaw بث الردود الجزئية في الوقت الحقيقي:

• الدردشات المباشرة: رسالة معاينة + editMessageText
• المجموعات/المواضيع: رسالة معاينة + 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 في وضع خادم تطبيق Codex. يُبقي Telegram هذه مفعّلة افتراضيًا لمطابقة سلوك OpenClaw الصادر من 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" فقط عندما تريد تسليمًا نهائيًا فقط: تُعطّل تعديلات معاينة Telegram ويُكتم حديث الأداة/التقدم العام بدلًا من إرساله كرسائل حالة مستقلة. لا تزال مطالبات الموافقة، وحمولات الوسائط، والأخطاء تُوجّه عبر التسليم النهائي العادي. استخدم streaming.preview.toolProgress: false عندما تريد فقط إبقاء تعديلات معاينة الإجابة مع إخفاء أسطر حالة تقدم الأدوات.

للردود النصية فقط:

• معاينات DM/المجموعة/الموضوع القصيرة: يحافظ OpenClaw على رسالة المعاينة نفسها وينفذ التحرير النهائي في مكانه
• النهائيات النصية الطويلة التي تنقسم إلى عدة رسائل Telegram تعيد استخدام المعاينة الموجودة كأول جزء نهائي عندما يكون ذلك ممكنًا، ثم ترسل الأجزاء المتبقية فقط
• تمسح نهائيات وضع التقدم مسودة الحالة وتستخدم التسليم النهائي العادي بدلًا من تحرير المسودة إلى الإجابة
• إذا فشل التحرير النهائي قبل تأكيد النص المكتمل، يستخدم OpenClaw التسليم النهائي العادي وينظف المعاينة القديمة

للردود المعقدة (مثل حمولات الوسائط)، يعود OpenClaw إلى التسليم النهائي العادي ثم ينظف رسالة المعاينة.

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

سلوك بث الاستدلال:

• يستخدم /reasoning stream مسار معاينة الاستدلال لقناة مدعومة؛ على Telegram، يبث الاستدلال داخل المعاينة المباشرة أثناء التوليد
• تُحذف معاينة الاستدلال بعد التسليم النهائي؛ استخدم /reasoning on عندما ينبغي أن يبقى الاستدلال مرئيًا
• تُرسل الإجابة النهائية دون نص الاستدلال

يستخدم النص الصادر رسائل Telegram HTML القياسية افتراضيًا حتى تبقى الردود قابلة للقراءة عبر عملاء Telegram الحاليين. يدعم وضع التوافق هذا التنسيق العادي للخط العريض، والمائل، والروابط، والكود، والمفسدات، والاقتباسات، لكنه لا يدعم كتل Bot API 10.1 الغنية فقط مثل الجداول الأصلية، والتفاصيل، والوسائط الغنية، والصيغ.

اضبط channels.telegram.richMessages: true لتفعيل رسائل Bot API 10.1 الغنية:

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

عند التفعيل:

• يُخبر الوكيل بأن رسائل Telegram الغنية متاحة لهذا البوت/الحساب.
• يُعرض نص Markdown عبر Markdown IR الخاص بـ OpenClaw ويُرسل كـ HTML غني في Telegram.
• تحافظ حمولات HTML الغنية الصريحة على وسوم Bot API 10.1 المدعومة مثل العناوين، والجداول، والتفاصيل، والوسائط الغنية، والصيغ.
• لا تزال تعليقات الوسائط تستخدم تعليقات Telegram HTML لأن الرسائل الغنية لا تستبدل التعليقات.

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

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

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

يُعالج تسجيل قائمة أوامر Telegram عند بدء التشغيل باستخدام setMyCommands.

افتراضيات الأوامر الأصلية:

• يفعّل commands.native: "auto" الأوامر الأصلية لـ Telegram

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

{channels: {telegram: {  customCommands: [    { command: "backup", description: "Git backup" },    { command: "generate", description: "Create an image" },  ],},},}

القواعد:

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

ملاحظات:

• الأوامر المخصصة هي إدخالات قائمة فقط؛ ولا تنفذ السلوك تلقائيًا
• يمكن أن تظل أوامر Plugin/المهارة تعمل عند كتابتها حتى إن لم تظهر في قائمة Telegram

إذا عُطلت الأوامر الأصلية، تُزال الأوامر المضمنة. قد تظل أوامر مخصصة/Plugin تُسجل إذا كانت مُعدة.

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

• يعني setMyCommands failed مع BOT_COMMANDS_TOO_MUCH أن قائمة Telegram لا تزال تتجاوز الحد بعد التقليم؛ قلّل أوامر Plugin/المهارة/المخصصة أو عطّل 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)

عند تثبيت Plugin device-pair:

1. ينشئ /pair كود إعداد
2. الصق الكود في تطبيق iOS
3. يعرض /pair pending الطلبات المعلقة (بما في ذلك الدور/النطاقات)
4. وافق على الطلب:
   • /pair approve <requestId> للموافقة الصريحة
   • /pair approve عندما لا يوجد إلا طلب معلق واحد
   • /pair approve latest للأحدث

يحمل كود الإعداد رمز تمهيد قصير الأجل. يُرجع تمهيد كود الإعداد المضمن رمز عقدة دائمًا مع scopes: [] إضافة إلى رمز تسليم مشغل محدود للإعداد الموثوق على الهاتف المحمول. يستطيع رمز المشغل هذا قراءة الإعداد الأصلي وقت الإعداد، لكنه لا يمنح نطاقات تعديل الإقران أو operator.admin.

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

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

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

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

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

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

النطاقات:

• off
• dm
• group
• all
• allowlist (افتراضي)

يربط capabilities: ["inlineButtons"] القديم إلى inlineButtons: "all".

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

{action: "send",channel: "telegram",to: "123456789",message: "Choose an option:",buttons: [[  { text: "Yes", callback_data: "yes" },  { text: "No", callback_data: "no" },],[{ text: "Cancel", callback_data: "cancel" }],],}

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

{action: "send",channel: "telegram",to: "123456789",message: "Open app:",presentation: {blocks: [  {    type: "buttons",    buttons: [{ label: "Launch", web_app: { url: "https://example.com/app" } }],  },],},}

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

نقرات رد الاتصال التي لا يطالب بها معالج تفاعلي مسجل من Plugin تُمرر إلى الوكيل كنص: callback_data: <value>

تتضمن إجراءات أداة Telegram:

• 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
• channels.telegram.actions.deleteMessage
• channels.telegram.actions.reactions
• channels.telegram.actions.sticker (افتراضي: معطل)

ملاحظة: edit وtopic-create مفعّلان حاليًا افتراضيًا ولا يملكان مفاتيح تبديل channels.telegram.actions.* منفصلة. تستخدم عمليات الإرسال في وقت التشغيل لقطة الإعدادات/الأسرار النشطة (بدء التشغيل/إعادة التحميل)، لذلك لا تنفذ مسارات الإجراءات إعادة حل SecretRef مخصصة لكل عملية إرسال.

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

يدعم Telegram وسوم ترابط ردود صريحة في المخرجات المولدة:

• [[reply_to_current]] يرد على الرسالة المحفزة
• [[reply_to:<id>]] يرد على معرف رسالة Telegram محدد

يتحكم channels.telegram.replyToMode في المعالجة:

• off (افتراضي)
• first
• all

عند تمكين ترابط الردود وتوفر نص Telegram الأصلي أو التعليق التوضيحي، يضمّن OpenClaw تلقائيًا مقتطف اقتباس Telegram أصليًا. يحد 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" },      // General topic → main agent            "3": { agentId: "zu" },        // Dev topic → zu agent            "5": { agentId: "coder" }      // Code review → coder agent          }        }      }    }  }}

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

ربط موضوع ACP الدائم: يمكن لمواضيع المنتدى تثبيت جلسات حزمة 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 ببيانات الرد الوصفية؛ ولا تستخدم مفاتيح جلسات واعية بالسلاسل إلا عندما يبلّغ Telegram getMe عن 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,}

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

الملصقات

التعامل مع الملصقات الواردة:

• static WEBP: يتم تنزيلها ومعالجتها (العنصر النائب <media:sticker>)
• animated TGS: يتم تخطيها
• video 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: "cat waving",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 لرسالة واردة. يحدد ackReactionScope متى يُرسل ذلك الرمز فعليًا.

ترتيب حل الرمز التعبيري (ackReaction):

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

ملاحظات:

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

النطاق (messages.ackReactionScope):

يقرأ موفر Telegram النطاق من 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 وwebhookHost وwebhookPort (القيم الافتراضية /telegram-webhook و127.0.0.1 و8787).

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

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

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

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

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

openclaw message send --channel telegram --target 123456789 --message "hi"openclaw message send --channel telegram --target @name --message "hi"openclaw message send --channel telegram --target -1001234567890:topic:42 --message "hi topic"

تستخدم استطلاعات Telegram الأمر openclaw message poll وتدعم مواضيع المنتديات:

openclaw message poll --channel telegram --target 123456789 \--poll-question "Ship it?" --poll-option "Yes" --poll-option "No"openclaw message poll --channel telegram --target -1001234567890:topic:42 \--poll-question "Pick a time" --poll-option "10am" --poll-option "2pm" \--poll-duration-seconds 300 --poll-public

أعلام الاستطلاع الخاصة بـ Telegram فقط:

• --poll-duration-seconds (5-600)
• --poll-anonymous
• --poll-public
• --thread-id لمواضيع المنتديات (أو استخدم هدف :topic:)

يدعم إرسال Telegram أيضًا:

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

ضبط الإجراءات:

• يعطّل channels.telegram.actions.sendMessage=false رسائل Telegram الصادرة، بما في ذلك الاستطلاعات
• يعطّل channels.telegram.actions.poll=false إنشاء استطلاعات Telegram مع إبقاء الإرسال العادي مفعّلًا

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

مسار الإعداد:

• channels.telegram.execApprovals.enabled (يُفعّل تلقائيًا عندما يمكن حل موافق واحد على الأقل)
• 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/Skill/الأوامر المخصصة أو عطّل القوائم الأصلية
• تكون استدعاءات بدء التشغيل deleteMyCommands / setMyCommands واستدعاءات الكتابة sendChatAction محدودة وتُعاد محاولتها مرة واحدة عبر احتياطي النقل في Telegram عند انتهاء مهلة الطلب. تشير أخطاء الشبكة/الجلب المستمرة عادةً إلى مشكلات في إمكانية الوصول إلى DNS/HTTPS نحو api.telegram.org

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

• يمكن أن يؤدي Node 22+ مع جلب/وكيل مخصص إلى سلوك إجهاض فوري إذا اختلفت أنواع AbortSignal.
• تحل بعض المضيفات api.telegram.org إلى IPv6 أولًا؛ وقد يتسبب خروج IPv6 المعطّل في إخفاقات متقطعة في Telegram API.
• إذا تضمنت السجلات TypeError: fetch failed أو Network request for 'getUpdates' failed!، فإن OpenClaw يعيد الآن محاولة هذه الأخطاء كأخطاء شبكة قابلة للاسترداد.
• أثناء بدء الاستطلاع، يعيد OpenClaw استخدام فحص بدء التشغيل الناجح getMe لصالح grammY حتى لا يحتاج المشغّل إلى getMe ثانٍ قبل أول getUpdates.
• إذا فشل deleteWebhook بخطأ شبكة عابر أثناء بدء الاستطلاع، يواصل OpenClaw الدخول في الاستطلاع الطويل بدل إجراء استدعاء آخر لمستوى التحكم قبل الاستطلاع. يظهر Webhook الذي لا يزال نشطًا كتعارض في getUpdates؛ ثم يعيد OpenClaw بناء نقل Telegram ويحاول تنظيف Webhook مرة أخرى.
• إذا كانت مقابس Telegram تُعاد تدويرها بوتيرة ثابتة قصيرة، فتحقق من انخفاض channels.telegram.timeoutSeconds؛ تقيّد عملاء البوت القيم المضبوطة تحت حواجز الطلب الصادر و getUpdates، لكن الإصدارات الأقدم كان يمكن أن تجهض كل استطلاع أو رد عند ضبط هذا تحت تلك الحواجز.
• إذا تضمنت السجلات Polling stall detected، يعيد OpenClaw تشغيل الاستطلاع ويعيد بناء نقل Telegram بعد 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 عبر OPENCLAW_PROXY_URL لبيئة خدمة ولم توجد متغيرات بيئة وكيل قياسية، يستخدم Telegram ذلك العنوان لنقل Bot API أيضًا.
• على مضيفات VPS ذات خروج/TLS مباشر غير مستقر، وجّه استدعاءات Telegram API عبر channels.telegram.proxy:

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؛ وإذا لم ينطبق أي منها، يعود Node 22+ إلى ipv4first.
• إذا كان المضيف لديك هو WSL2 أو يعمل صراحة بشكل أفضل مع سلوك IPv4 فقط، فافرض اختيار العائلة:

channels:telegram:network:  autoSelectFamily: false

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

channels:telegram:network:  dangerouslyAllowPrivateNetwork: true

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

• تجاوزات البيئة (مؤقتة):
  • 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