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 (تسمية الأداة فقط)
• يتم اكتشاف channels.telegram.streamMode القديم وقيم streaming المنطقية؛ شغّل openclaw doctor --fix لترحيلها إلى channels.telegram.streaming.mode

تحديثات معاينة تقدم الأدوات هي أسطر الحالة القصيرة التي تظهر أثناء تشغيل الأدوات، مثل تنفيذ الأوامر، وقراءة الملفات، وتحديثات التخطيط، أو ملخصات التصحيحات. يبقي 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 عندما تريد فقط الإبقاء على تعديلات معاينة الإجابة مع إخفاء أسطر حالة تقدم الأدوات.

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

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

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

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

بث الاستدلال الخاص بـ Telegram فقط:

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

يستخدم النص الصادر parse_mode: "HTML" في Telegram.

• يُعرض النص الشبيه بـ Markdown كـ HTML آمن لـ Telegram.
• تُحفظ وسوم HTML المدعومة في Telegram؛ ويُهرّب HTML غير المدعوم.
• إذا رفض Telegram HTML المحلل، يعيد OpenClaw المحاولة كنص عادي.

تكون معاينات الروابط مفعلة افتراضيًا ويمكن تعطيلها باستخدام 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/skill أن تستمر في العمل عند كتابتها حتى لو لم تظهر في قائمة Telegram

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

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

• يعني setMyCommands failed مع BOT_COMMANDS_TOO_MUCH أن قائمة Telegram ما زالت تتجاوز الحد بعد التقليص؛ قلّل أوامر plugin/skill/المخصصة أو عطّل 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.approvals وoperator.read وoperator.talk.secrets وoperator.write. فحوصات نطاق التمهيد مسبوقة بالدور، لذلك لا تلبي قائمة السماح الخاصة بالمشغل إلا طلبات المشغل؛ ما زالت الأدوار غير المشغّلة تحتاج إلى نطاقات تحت بادئة الدور الخاصة بها.

إذا أعاد جهاز المحاولة بتفاصيل مصادقة متغيرة (مثل الدور/النطاقات/المفتاح العام)، يُستبدل الطلب المعلق السابق ويستخدم الطلب الجديد 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" }],],}

تُمرر نقرات Callback إلى الوكيل كنص: callback_data: <value>

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

• sendMessage (to، content، mediaUrl اختياري، replyToMessageId، messageThreadId)
• react (chatId، messageId، emoji)
• deleteMessage (chatId، messageId)
• editMessage (chatId، messageId، content)
• 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 خاص بالموضوع فقط ولا يرث من الإعدادات الافتراضية للمجموعة.

توجيه الوكيل لكل موضوع: يمكن لكل موضوع التوجيه إلى وكيل مختلف بتعيين 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 typed ذات المستوى الأعلى (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 بتوجيه الرسائل المباشرة وبيانات الرد الوصفية في جلسات مسطحة افتراضيا؛ ولا تستخدم مفاتيح جلسات مدركة للمحادثات إلا عند تكوينها باستخدام threadReplies: "inbound" أو threadReplies: "always" أو requireTopic: true أو تكوين موضوع مطابق. استخدم channels.telegram.dm.threadReplies ذي المستوى الأعلى للقيمة الافتراضية للحساب، أو direct.<chatId>.threadReplies لرسالة مباشرة واحدة.

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

يميز 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,}

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

الملصقات

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

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

حقول سياق الملصق:

• Sticker.emoji
• Sticker.setName
• Sticker.fileId
• Sticker.fileUniqueId
• Sticker.cachedDescription

ملف ذاكرة التخزين المؤقت للملصقات:

• ~/.openclaw/telegram/sticker-cache.json

توصف الملصقات مرة واحدة (عند الإمكان) وتُخزن مؤقتا لتقليل استدعاءات الرؤية المتكررة.

تفعيل إجراءات الملصقات:

{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 لرسالة واردة.

ترتيب الحل:

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

ملاحظات:

• يتوقع Telegram إيموجي unicode (على سبيل المثال "👀").
• استخدم "" لتعطيل التفاعل لقناة أو حساب.

تكون كتابات تكوين القناة مفعلة افتراضيا (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 بعد ذلك التحديث بشكل غير متزامن عبر المسارات نفسها لكل دردشة/لكل موضوع في البوت المستخدمة في الاستقصاء الطويل، لذلك لا تجعل دورات الوكيل البطيئة ACK التسليم الخاص بـ Telegram منتظرا.

• القيمة الافتراضية لـ channels.telegram.textChunkLimit هي 4000.
• يفضل channels.telegram.chunkMode="newline" حدود الفقرات (الأسطر الفارغة) قبل التقسيم حسب الطول.
• يحد channels.telegram.mediaMaxMb (الافتراضي 100) حجم وسائط Telegram الواردة والصادرة.
• يتحكم channels.telegram.mediaGroupFlushMs (الافتراضي 500) في مدة تخزين ألبومات/مجموعات وسائط Telegram مؤقتا قبل أن يرسلها OpenClaw كرسالة واردة واحدة. زِدها إذا كانت أجزاء الألبوم تصل متأخرة؛ وقللها لتقليل زمن تأخر الرد على الألبوم.
• يتجاوز channels.telegram.timeoutSeconds مهلة عميل API في Telegram (إذا لم يُعين، تطبق القيمة الافتراضية لـ grammY). تقيّد عملاء البوت القيم المكوّنة الأقل من حارس طلب النص/الكتابة الصادر البالغ 60 ثانية حتى لا يوقف grammY تسليم الرد المرئي قبل أن يتمكن حارس نقل OpenClaw والرجوع الاحتياطي من العمل. لا يزال الاستقصاء الطويل يستخدم حارس طلب getUpdates مدته 45 ثانية حتى لا تُترك عمليات الاستقصاء الخاملة إلى أجل غير محدد.
• القيمة الافتراضية لـ channels.telegram.pollingStallThresholdMs هي 120000؛ اضبطها بين 30000 و600000 فقط لحالات إعادة تشغيل تعثر الاستقصاء الإيجابية الكاذبة.
• يستخدم سجل سياق المجموعة channels.telegram.historyLimit أو messages.groupChat.historyLimit (الافتراضي 50)؛ وتقوم 0 بالتعطيل.
• يُطبع سياق الرد/الاقتباس/إعادة التوجيه التكميلي في نافذة سياق محادثة مختارة واحدة عندما يكون Gateway قد رصد الرسائل الأصلية؛ وتُحفظ ذاكرة التخزين المؤقت للرسائل المرصودة بجوار مخزن الجلسات. لا يتضمن 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+ مع fetch/proxy مخصص إلى سلوك إجهاض فوري إذا لم تتطابق أنواع 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 الطويلة سليمة لكن مضيفك لا يزال يبلّغ عن عمليات إعادة تشغيل كاذبة بسبب تعثر الاستقصاء. تشير التعثرات المستمرة عادةً إلى مشكلات في proxy أو DNS أو IPv6 أو خروج TLS بين المضيف وapi.telegram.org.
• يراعي Telegram أيضًا متغيرات بيئة proxy الخاصة بالعملية لنقل Bot API، بما في ذلك HTTP_PROXY وHTTPS_PROXY وALL_PROXY وصيغها بالأحرف الصغيرة. لا يزال بإمكان NO_PROXY / no_proxy تجاوز api.telegram.org.
• إذا ضُبط proxy المُدار من OpenClaw عبر OPENCLAW_PROXY_URL لبيئة خدمة ولم تكن هناك متغيرات بيئة proxy قياسية، يستخدم Telegram ذلك URL لنقل 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 افتراضيًا. إذا كان fake-IP موثوق أو proxy شفاف يعيد كتابة api.telegram.org إلى عنوان خاص/داخلي/ذي استخدام خاص آخر أثناء تنزيلات الوسائط، يمكنك الاشتراك في التجاوز الخاص بـ Telegram فقط:

channels:telegram:network:  dangerouslyAllowPrivateNetwork: true

• يتوفر الاشتراك نفسه لكل حساب في channels.telegram.accounts.<accountId>.network.dangerouslyAllowPrivateNetwork.
• إذا كان proxy لديك يحل مضيفات وسائط 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