منصات المراسلة
تيليجرام
الحالة: جاهز للإنتاج للرسائل الخاصة للبوت + المجموعات عبر grammY. الاقتراع الطويل هو الوضع الافتراضي؛ وضع webhook اختياري.
الإعداد السريع
الخطوة 1: إنشاء الرمز المميز للبوت في BotFather
افتح تيليجرام وتحدث مع @BotFather (تأكد من أن المعرف هو بالضبط @BotFather).شغل /newbot، اتبع التعليمات، واحفظ الرمز المميز.
الخطوة 2: تكوين الرمز المميز وسياسة الرسائل ا لخاصة
{
channels: {
telegram: {
enabled: true,
botToken: "123:abc",
dmPolicy: "pairing",
groups: { "*": { requireMention: true } },
},
},
}
البديل البيئي: TELEGRAM_BOT_TOKEN=... (الحساب الافتراضي فقط). تيليجرام لا يستخدم openclaw channels login telegram؛ قم بتكوين الرمز المميز في config/env، ثم ابدأ البوابة.
الخطوة 3: ابدأ البوابة ووافق على أول رسالة خاصة
openclaw gateway
openclaw pairing list telegram
openclaw pairing approve telegram <CODE>
رموز الاقتران تنتهي صلاحيتها بعد ساعة واحدة.
الخطوة 4: أضف البوت إلى مجموعة
أضف البوت إلى مجموعتك، ثم عيّن channels.telegram.groups و groupPolicy لتتوافق مع نموذج الوصول الخاص بك.
ℹ️ ترتيب حل الرمز المميز يراعي الحساب. عمليًا، قيم التكوين تفوق البديل البيئي، و
TELEGRAM_BOT_TOKENينطبق فقط على الحساب الافتراضي.
إعدادات جانب تيليجرام
بوتات تيليجرام تفترض بشكل افتراضي وضع الخصوصية، مما يحد من رسائل المجموعة التي تتلقاها.إذا كان يجب على البوت رؤية جميع رسائل المجموعة، إما:
- قم بتعطيل وضع الخصوصية عبر
/setprivacy، أو - اجعل البوت مشرفًا على المجموعة.
عند تبديل وضع الخصوصية، أزل وأعد إضافة البوت في كل مجموعة حتى يطبق تيليجرام التغيير.
حالة المشرف يتم التحكم بها في إعدادات مجموعة تيليجرام.البوتات المشرفة تتلقى جميع رسائل المجموعة، وهو أمر مفيد لسلوك المجموعة الدائم.
/setjoingroupsللسماح/رفض الإضافة إلى المجموعات/setprivacyلسلوك مدى الرؤية في المجموعات
التحكم في الوصول والتفعيل
سلوك التشغيل
- تيليجرام مملوك من قبل عملية البوابة.
- التوجيه حتمي: الردود الواردة من تيليجرام تعود إلى تيليجرام (النموذج لا يختار القنوات).
- الرسائل الواردة تُطبع إلى ظرف القناة المشترك مع بيانات الرد والعناصر النائبة للوسائط.
- جلسات المجموعات معزولة حسب معرف المجموعة. مواضيع المنتدى تضيف
:topic:للحفاظ على عزل المواضيع. - رسائل الرسائل الخاصة يمكن أن تحمل
message_thread_id؛ OpenClaw يوجهها بمفاتيح جلسة تراعي الخيط ويحفظ معرف الخيط للردود. - الاقتراع الطويل يستخدم مشغل grammY مع تسلسل لكل محادثة/خيط. إجمالي تزامن مصرف المشغل يستخدم
agents.defaults.maxConcurrent. - واجهة برمجة تطبيقات بوت تيليجرام لا تدعم إيصالات القراءة (
sendReadReceiptsلا ينطبق).
مرجع الميزات
يمكن لـ OpenClaw بث الردود الجزئية في الوقت الفعلي:
- المحادثات المباشرة: بث المسودات الأصلية لتيليجرام عبر
sendMessageDraft - المجموعات/المواضيع: رسالة معاينة +
editMessageText
المتطلب:
channels.telegram.streamingهيoff | partial | block | progress(الافتراضي:partial)progressتُعيّن إلىpartialعلى تيليجرام (توافق مع تسمية عبر القنوات)- القيم القديمة
channels.telegram.streamModeوالقيم المنطقيةstreamingتُعيّن تلقائيًا
تيليجرام مكّن sendMessageDraft لجميع البوتات في Bot API 9.5 (1 مارس 2026).للردود النصية فقط:
- الرسائل الخاصة: OpenClaw يحدّث المسودة في مكانها (لا توجد رسالة معاينة إضافية)
- المجموعة/الموضوع: OpenClaw يحتفظ بنفس رسالة المعاينة ويقوم بتعديل نهائي في مكانها (لا توجد رسالة ثانية)
للردود المعقدة (على سبيل المثال حمولات الوسائط)، OpenClaw يتراجع إلى التسليم النهائي العادي ثم ينظف رسالة المعاينة.بث المعاينة منفصل عن بث الكتل. عندما يتم تمكين بث الكتل صراحةً لتيليجرام، يتخطى OpenClaw بث المعاينة لتجنب البث المزدوج.إذا كان نقل المسودة الأصلية غير متاح/مرفوض، يتراجع OpenClaw تلقائيًا إلى sendMessage + editMessageText.تيليجرام فقط تيار التفكير:
/reasoning streamيرسل التفكير إلى معاينة البث المباشر أثناء التوليد- الإجابة النهائية تُرسل بدون نص التفكير
النص الصادر يستخدم تيليجرام parse_mode: "HTML".
- النص الشبيه بـ Markdown يُصاغ إلى HTML آمن لتيليجرام.
- HTML النموذج الخام يُهرب لتقليل فشل تحليل تيليجرام.
- إذا رفض تيليجرام HTML المحلل، يعيد OpenClaw المحاولة كنص عادي.
معاينات الروابط مفعلة افتراضيًا ويمكن تعطيلها بـ channels.telegram.linkPreview: false.
تسجيل قائمة أوامر تيليجرام يتم التعامل معه عند بدء التشغيل بـ setMyCommands.الأوامر الأصلية الافتراضية:
commands.native: "auto"يُفعّل الأوامر الأصلية لتيليجرام
أضف إدخالات قائمة أوامر مخصصة:
{
channels: {
telegram: {
customCommands: [
{ command: "backup", description: "نسخ احتياطي Git" },
{ command: "generate", description: "إنشاء صورة" },
],
},
},
}
القواعد:
- الأسماء تُطبّع (إزالة
/البادئة، أحرف صغيرة) - النمط الصالح:
a-z,0-9,_, الطول1..32 - الأوامر المخصصة لا يمكنها تجاوز الأوامر الأصلية
- التعارضات/التكرارات يتم تخطيها وتسجيلها
ملا حظات:
- الأوامر المخصصة هي إدخالات قائمة فقط؛ لا تنفذ السلوك تلقائيًا
- أوامر الإضافات/المهارات يمكن أن تعمل عند كتابتها حتى لو لم تظهر في قائمة تيليجرام
إذا تم تعطيل الأوامر الأصلية، تُزال الأوامر المدمجة. الأوامر المخصصة/الإضافية قد تسجل إذا تم تكوينها.فشل الإعداد الشائع:
setMyCommands failedيعني عادةً أن DNS/HTTPS الصادر إلىapi.telegram.orgمحظور.
أوامر اقتران الجهاز (إضافة device-pair)
عند تثبيت إضافة device-pair:
/pairيولد رمز إعداد- الصق الرمز في تطبيق iOS
/pair approveيوافق على أحدث طلب معلق
المزيد من التفاصيل: الاقتران.
تكوين نطاق لوحة المفاتيح المضمنة:
{
channels: {
telegram: {
capabilities: {
inlineButtons: "allowlist",
},
},
},
}
تجاوز لكل حساب:
{
channels: {
telegram: {
accounts: {
main: {
capabilities: {
inlineButtons: "allowlist",
},
},
},
},
},
}
النطاقات:
offdmgroupallallowlist(الافتراضي)
التراث capabilities: ["inlineButtons"] يُعيّن إلى inlineButtons: "all".مثال على إجراء الرسالة:
{
action: "send",
channel: "telegram",
to: "123456789",
message: "اختر خيارًا:",
buttons: [
[
{ text: "نعم", callback_data: "yes" },
{ text: "لا", callback_data: "no" },
],
[{ text: "إلغاء", callback_data: "cancel" }],
],
}
نقرات الرد تُمرّر إلى الوكيل كنص: callback_data:
إجراءات أداة تيليجرام تتضمن:
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.sendMessagechannels.telegram.actions.deleteMessagechannels.telegram.actions.reactionschannels.telegram.actions.sticker(الافتراضي: معطل)
ملاحظة: edit و topic-create مفعلان افتراضيًا حاليًا وليس لهما مفاتيح تبديل منفصلة channels.telegram.actions.*.دلالات إزالة التفاعل: /tools/reactions
تيليجرام يدعم وسوم خيط الرد الصريحة في المخرجات المُنشأة:
[[reply_to_current]]يرد على الرسالة المشغلة[[reply_to:]]يرد على معرف رسالة تيليجرام محدد
channels.telegram.replyToMode يتحكم في المعالجة:
off(الافتراضي)firstall
ملاحظة: off يعطل خيط الرد الضمني. وسوم [[reply_to_*]] الصريحة لا تزال تُحترم.
مجموعات المنتدى الفائقة:
- مفاتيح جلسة الموضوع تضيف
:topic: - الردود والكتابة تستهدف خيط الموضوع
- مسار تكوين الموضوع:
channels.telegram.groups..topics.
حالة خاصة للموضوع العام (threadId=1):
- إرسال الرسائل يحذف
message_thread_id(تيليجرام يرفضsendMessage(...thread_id=1)) - إجراءات الكتابة لا تزال تتضمن
message_thread_id
توارث الموضوع: إدخالات الموضوع ترث إعدادات المجموعة ما لم يتم تجاوزها (requireMention, allowFrom, skills, systemPrompt, enabled, groupPolicy). agentId خاص بالموضوع فقط ولا يرث من إعدادات المجموعة الافتراضية.توجيه الوكيل لكل موضوع: يمكن لكل موضوع توجيه إلى وكيل مختلف عن طريق تعيين agentId في تكوين الموضوع. هذا يعطي لكل موضوع مساحة عمل وذاكرة وجلسة معزولة خاصة به. مثال:
{
channels: {
telegram: {
groups: {
"-1001234567890": {
topics: {
"1": { agentId: "main" }, // الموضوع العام → الوكيل الرئيسي
"3": { agentId: "zu" }, // موضوع التطوير → وكيل zu
"5": { agentId: "coder" } // مراجعة الكود → وكيل coder
}
}
}
}
}
}
كل موضوع له بعد ذلك مفتاح جلسة خاص به: agent:zu:telegram:group:-1001234567890:topic:3ربط موضوع ACP الدائم: يمكن لمواضيع المنتدى تثبيت جلسات ACP عبر روابط ACP مكتوبة على المستوى الأعلى:
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 مرتبط بالخيط من المحادثة:
/acp spawn --thread here|autoيمكنه ربط موضوع تيليجرام الحالي بجلسة ACP جديدة.- رسائل الموضوع اللاحقة تُوجّه مباشرة إلى جلسة ACP المرتبطة (لا حاجة لـ
/acp steer). - OpenClaw يثبت رسالة تأكيد الإنشاء داخل الموضوع بعد ربط ناجح.
- يتطلب
channels.telegram.threadBindings.spawnAcpSessions=true.
سياق القالب يتضمن:
MessageThreadIdIsForum
سلوك خيط الرسائل الخاصة:
- المحادثات الخاصة مع
message_thread_idتحتفظ بتوجيه الرسائل الخاصة ولكن تستخدم مفاتيح جلسة/أهداف رد تراعي الخيط.