Telegram

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

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

• الدردشات المباشرة: رسالة معاينة + 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

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

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

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

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

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

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

• يفعّل 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

• يعني 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)

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

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

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

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

{
  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" }],
  ],
}

• sendMessage (to، content، mediaUrl اختياري، replyToMessageId، messageThreadId)
• react (chatId، messageId، emoji)
• deleteMessage (chatId، messageId)
• editMessage (chatId، messageId، content)
• createForumTopic (chatId، name، iconColor اختياري، iconCustomEmojiId)

• channels.telegram.actions.sendMessage
• channels.telegram.actions.deleteMessage
• channels.telegram.actions.reactions
• channels.telegram.actions.sticker (الافتراضي: معطل)

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

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

• تضيف مفاتيح جلسة الموضوع :topic:<threadId>
• تستهدف الردود وإجراءات الكتابة سلسلة الموضوع
• مسار إعداد الموضوع: channels.telegram.groups.<chatId>.topics.<threadId>

• تحذف إرسالات الرسائل message_thread_id (يرفض Telegram sendMessage(...thread_id=1))
• ما زالت إجراءات الكتابة تتضمن message_thread_id

{
  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
          }
        }
      }
    }
  }
}

​

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

• الافتراضي: سلوك الملف الصوتي
• الوسم [[audio_as_voice]] في رد الوكيل لفرض الإرسال كملاحظة صوتية
• تُؤطر نصوص الملاحظات الصوتية الواردة كنص مولد آليا وغير موثوق في سياق الوكيل؛ ويظل اكتشاف الإشارات يستخدم النص الخام بحيث تستمر الرسائل الصوتية المحكومة بالإشارات في العمل.

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

​

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

{
  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 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)، وليس إلى الموضوع الأصلي الدقيق

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

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

• أحداث ترحيل المجموعة (migrate_to_chat_id) لتحديث channels.telegram.groups
• /config set و/config unset (يتطلب تفعيل الأوامر)

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

• القيمة الافتراضية لـ 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 قبل الاتصال، لكنه لا يعيد محاولة مغلفات الشبكة الغامضة بعد الإرسال التي قد تكرر الرسائل المرئية.

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"

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

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

• --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 مع ترك الإرسال العادي مفعلا

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

• إذا كان 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 A
dig +short api.telegram.org AAAA