Telegram

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

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

• القيمة 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 لترحيلها

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

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

• ظهور 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

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

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

​

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

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

​

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

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

​

الملصقات

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

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

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

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

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

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

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

• channels.telegram.execApprovals.enabled (يُفعّل "auto" عند إمكانية التعرّف على موافق واحد على الأقل)
• 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 أو 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 A
dig +short api.telegram.org AAAA