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

• /setjoingroups للسماح/منع الإضافة إلى المجموعات
• /setprivacy لسلوك الرؤية داخل المجموعات

• الدردشات الخاصة: رسالة معاينة + editMessageText
• المجموعات/الموضوعات: رسالة معاينة + editMessageText

• أن تكون channels.telegram.streaming إحدى القيم off | partial | block | progress (الافتراضي: partial)
• تُحوَّل progress إلى partial على Telegram (للتوافق مع التسمية عبر القنوات)
• تُحوَّل تلقائيًا قيم channels.telegram.streamMode القديمة وقيم streaming المنطقية

• الرسائل الخاصة: يحتفظ OpenClaw برسالة المعاينة نفسها ويجري تعديلًا نهائيًا في المكان نفسه (من دون رسالة ثانية)
• المجموعة/الموضوع: يحتفظ OpenClaw برسالة المعاينة نفسها ويجري تعديلًا نهائيًا في المكان نفسه (من دون رسالة ثانية)

• /reasoning stream يرسل الاستدلال إلى المعاينة المباشرة أثناء التوليد
• يُرسل الجواب النهائي من دون نص الاستدلال

• يُعرَض النص الشبيه بـ Markdown إلى HTML آمن لـ Telegram.
• يُهَرب HTML الخام من النموذج لتقليل حالات فشل التحليل في Telegram.
• إذا رفض 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/Skills في العمل عند كتابتها حتى إذا لم تظهر في قائمة Telegram

• فشل setMyCommands failed مع BOT_COMMANDS_TOO_MUCH يعني أن قائمة Telegram ما زالت زائدة بعد التقليص؛ قلّل أوامر plugin/Skills/الأوامر المخصصة أو عطّل channels.telegram.commands.native.
• فشل setMyCommands failed مع أخطاء الشبكة/fetch يعني عادةً أن DNS/HTTPS الصادر إلى api.telegram.org محجوب.

​

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

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>
• تستهدف الردود وإشارات الكتابة thread الخاص بالموضوع
• مسار تكوين الموضوع: 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" },      // الموضوع العام → الوكيل الرئيسي
            "3": { agentId: "zu" },        // موضوع التطوير → الوكيل zu
            "5": { agentId: "coder" }      // مراجعة الشيفرة → الوكيل coder
          }
        }
      }
    }
  }
}

• bindings[] مع type: "acp" وmatch.channel: "telegram"

{
  agents: {
    list: [
      {
        id: "codex",
        runtime: {
          type: "acp",
          acp: {
            agent: "codex",
            backend: "acpx",
            mode: "persistent",
            cwd: "/workspace/openclaw",
          },
        },
      },
    ],
  },
  bindings: [
    {
      type: "acp",
      agentId: "codex",
      match: {
        channel: "telegram",
        accountId: "default",
        peer: { kind: "group", id: "-1001234567890:topic:42" },
      },
    },
  ],
  channels: {
    telegram: {
      groups: {
        "-1001234567890": {
          topics: {
            "42": {
              requireMention: false,
            },
          },
        },
      },
    },
  },
}

• يمكن للأمر /acp spawn <agent> --thread here|auto ربط موضوع Telegram الحالي بجلسة ACP جديدة.
• تُوجَّه رسائل الموضوع اللاحقة مباشرة إلى جلسة ACP المرتبطة (من دون الحاجة إلى /acp steer).
• يثبت OpenClaw رسالة تأكيد الإنشاء داخل الموضوع بعد نجاح الربط.
• يتطلب channels.telegram.threadBindings.spawnAcpSessions=true.

• MessageThreadId
• IsForum

• تحافظ الدردشات الخاصة التي تحتوي على message_thread_id على توجيه الرسائل الخاصة لكنها تستخدم مفاتيح جلسة/أهداف رد تراعي thread.

​

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

• الافتراضي: سلوك ملف صوتي
• الوسم [[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 تفاعلات المستخدمين على الرسائل التي أرسلها البوت فقط (بأفضل جهد عبر cache الرسائل المرسلة).
• ما زالت أحداث التفاعل تراعي عناصر التحكم في الوصول في Telegram (dmPolicy وallowFrom وgroupPolicy وgroupAllowFrom)؛ ويُسقَط المرسلون غير المصرح لهم.
• لا يوفّر Telegram معرّفات thread في تحديثات التفاعل.
  • تُوجَّه المجموعات غير التابعة للمنتدى إلى جلسة دردشة المجموعة
  • وتُوجَّه مجموعات المنتدى إلى جلسة الموضوع العام للمجموعة (:topic:1)، وليس إلى الموضوع الأصلي بالضبط

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

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

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

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

• اضبط channels.telegram.webhookUrl
• اضبط channels.telegram.webhookSecret (مطلوب عند ضبط webhook URL)
• اختياريًا channels.telegram.webhookPath (الافتراضي /telegram-webhook)
• اختياريًا channels.telegram.webhookHost (الافتراضي 127.0.0.1)
• اختياريًا channels.telegram.webhookPort (الافتراضي 8787)

• القيمة الافتراضية لـ channels.telegram.textChunkLimit هي 4000.
• يفضّل channels.telegram.chunkMode="newline" حدود الفقرات (الأسطر الفارغة) قبل التقسيم حسب الطول.
• يحدد channels.telegram.mediaMaxMb (الافتراضي 100) الحد الأقصى لحجم الوسائط الواردة والصادرة في Telegram.
• يتجاوز channels.telegram.timeoutSeconds مهلة عميل Telegram API (إذا لم يُضبط، تُطبَّق القيمة الافتراضية لـ grammY).
• يستخدم سجل سياق المجموعات channels.telegram.historyLimit أو messages.groupChat.historyLimit (الافتراضي 50)؛ و0 يعطّل الميزة.
• يُمرَّر حاليًا سياق الرد/الاقتباس/إعادة التوجيه التكميلي كما تم استلامه.
• تعمل allowlists في Telegram أساسًا على تقييد من يمكنه تشغيل الوكيل، وليست حدًا كاملًا لتنقيح السياق التكميلي.
• عناصر التحكم في سجل الرسائل الخاصة:
  • channels.telegram.dmHistoryLimit
  • channels.telegram.dms["<user_id>"].historyLimit
• ينطبق تكوين channels.telegram.retry على مساعدات الإرسال الخاصة بـ Telegram (CLI/tools/actions) في أخطاء Telegram API الصادرة القابلة للاسترداد.

openclaw message send --channel telegram --target 123456789 --message "hi"
openclaw message send --channel telegram --target @name --message "hi"

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:)

• --buttons للوحات المفاتيح المضمنة عندما يسمح channels.telegram.capabilities.inlineButtons بذلك
• --force-document لإرسال الصور وملفات GIF الصادرة كمستندات بدلًا من تحميلات الصور المضغوطة أو الوسائط المتحركة

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

• channels.telegram.execApprovals.enabled
• channels.telegram.execApprovals.approvers (اختياري؛ ويرجع إلى معرّفات المالك الرقمية المستنتجة من allowFrom وdefaultTo المباشر عند الإمكان)
• channels.telegram.execApprovals.target (dm | channel | both، الافتراضي: dm)
• agentFilter وsessionFilter

• يرسل target: "dm" مطالبات الموافقة فقط إلى الرسائل الخاصة للموافقين الذين تم حلهم
• يرسل target: "channel" المطالبة مرة أخرى إلى دردشة/موضوع Telegram الأصلي
• يرسل target: "both" إلى الرسائل الخاصة للموافقين وإلى الدردشة/الموضوع الأصلي

• تُحل دائمًا معرّفات الموافقة المسبوقة بـ plugin: عبر موافقات plugin.
• تحاول معرّفات الموافقة الأخرى أولًا exec.approval.resolve.
• إذا كان Telegram مصرحًا له أيضًا بموافقات plugin وقالت البوابة إن موافقة exec غير معروفة/منتهية الصلاحية، يعيد Telegram المحاولة مرة واحدة عبر plugin.approval.resolve.
• لا تسقط حالات الرفض/الأخطاء الحقيقية الخاصة بـ exec بصمت إلى حل موافقات plugin.

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

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

• صرّح هوية المرسل الخاص بك (pairing و/أو allowFrom رقمية)
• ما زال تفويض الأوامر يطبّق حتى عندما تكون سياسة المجموعة open
• يعني setMyCommands failed مع BOT_COMMANDS_TOO_MUCH أن القائمة الأصلية تحتوي على عدد كبير جدًا من الإدخالات؛ قلّل أوامر plugin/Skills/الأوامر المخصصة أو عطّل القوائم الأصلية
• يشير setMyCommands failed مع أخطاء الشبكة/fetch عادةً إلى مشكلات في الوصول إلى DNS/HTTPS الخاص بـ api.telegram.org

• يمكن أن يؤدي Node 22+ مع fetch/proxy مخصص إلى سلوك إجهاض فوري إذا لم تتطابق أنواع AbortSignal.
• تحل بعض المضيفات api.telegram.org إلى IPv6 أولًا؛ وقد يؤدي خروج IPv6 المعطوب إلى أعطال متقطعة في Telegram API.
• إذا تضمنت السجلات TypeError: fetch failed أو Network request for 'getUpdates' failed!، فإن OpenClaw يعيد الآن محاولة هذه الحالات كأخطاء شبكة قابلة للاسترداد.
• على مضيفات VPS ذات الخروج/TLS المباشر غير المستقر، وجّه استدعاءات Telegram API عبر channels.telegram.proxy:

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

• يستخدم Node 22+ افتراضيًا autoSelectFamily=true (باستثناء WSL2) وdnsResultOrder=ipv4first.
• إذا كان مضيفك WSL2 أو يعمل صراحةً بشكل أفضل مع سلوك IPv4 فقط، فافرض اختيار family:

channels:
  telegram:
    network:
      autoSelectFamily: false

• تُسمح بالفعل افتراضيًا إجابات نطاق القياس RFC 2544 (198.18.0.0/15) لتنزيلات وسائط Telegram. وإذا كانت fake-IP موثوقة أو transparent 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