Telegram

ربات‌های Telegram به‌طور پیش‌فرض از Privacy Mode استفاده می‌کنند که پیام‌های گروهی دریافتی آن‌ها را محدود می‌کند.

برای مشاهده همه پیام‌های گروهی، یکی از این کارها را انجام دهید:

• حالت حریم خصوصی را از طریق /setprivacy غیرفعال کنید، یا
• ربات را مدیر گروه کنید.

پس از تغییر حالت حریم خصوصی، ربات را در هر گروه حذف و دوباره اضافه کنید تا Telegram تغییر را اعمال کند.

وضعیت مدیریت در تنظیمات گروه Telegram کنترل می‌شود. ربات‌های مدیر همه پیام‌های گروهی را دریافت می‌کنند که برای رفتار همیشه‌فعال در گروه مفید است.

• /setjoingroups — اجازه‌دادن/ندادن افزودن به گروه
• /setprivacy — رفتار مشاهده‌پذیری در گروه

اگر رابط کاربری را به فرمان‌های گفت‌وگو ترجیح می‌دهید، همین تنظیمات در برنامه وب BotFather نیز در دسترس هستند.

OpenClaw پاسخ‌های جزئی را به‌صورت بی‌درنگ در چت‌های مستقیم، گروه‌ها و موضوع‌ها پخش می‌کند: یک پیام پیش‌نمایش می‌فرستد، سپس بارها editMessageText را اجرا می‌کند و در همان‌جا آن را نهایی می‌کند.

• 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 را اجرا کنید

خط‌های پیشرفت ابزار، به‌روزرسانی‌های وضعیت کوتاهی هستند که هنگام اجرای ابزارها نمایش داده می‌شوند (اجرای فرمان، خواندن فایل‌ها، به‌روزرسانی‌های برنامه‌ریزی، خلاصه وصله‌ها و مقدمه/توضیحات Codex در حالت app-server). Telegram آن‌ها را به‌طور پیش‌فرض فعال نگه می‌دارد (مطابق رفتار منتشرشده از 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" ویرایش‌های پیش‌نمایش را غیرفعال و گفت‌وگوی عمومی ابزار/پیشرفت را به‌جای ارسال آن به‌صورت پیام‌های وضعیت مستقل سرکوب می‌کند؛ درخواست‌های تأیید، رسانه و خطاها همچنان از مسیر تحویل نهایی عادی ارسال می‌شوند. streaming.preview.toolProgress: false فقط ویرایش‌های پیش‌نمایش پاسخ را نگه می‌دارد.

برای پاسخ‌های فقط متنی: پیش‌نمایش‌های کوتاه، ویرایش نهایی را در همان‌جا دریافت می‌کنند؛ پاسخ‌های نهایی طولانی که به چند پیام تقسیم می‌شوند، از پیش‌نمایش به‌عنوان بخش اول دوباره استفاده می‌کنند و سپس فقط باقی‌مانده را می‌فرستند؛ پاسخ‌های نهایی حالت پیشرفت، پیش‌نویس وضعیت را پاک می‌کنند و از تحویل نهایی عادی استفاده می‌کنند؛ اگر ویرایش نهایی پیش از تأیید تکمیل ناموفق باشد، OpenClaw به تحویل نهایی عادی بازمی‌گردد و پیش‌نمایش کهنه را پاک می‌کند. برای پاسخ‌های پیچیده (محموله‌های رسانه‌ای)، OpenClaw همیشه به تحویل نهایی عادی بازمی‌گردد و پیش‌نمایش را پاک می‌کند.

پخش پیش‌نمایش و پخش بلوکی با یکدیگر ناسازگارند — وقتی پخش بلوکی صراحتاً فعال باشد، OpenClaw برای جلوگیری از پخش دوگانه، پخش پیش‌نمایش را رد می‌کند.

استدلال: /reasoning stream هنگام تولید، استدلال را در پیش‌نمایش زنده پخش می‌کند و سپس پس از تحویل نهایی، پیش‌نمایش استدلال را حذف می‌کند (برای قابل‌مشاهده نگه‌داشتن آن از /reasoning on استفاده کنید). پاسخ نهایی بدون متن استدلال ارسال می‌شود.

متن خروجی به‌طور پیش‌فرض از پیام‌های استاندارد HTML در Telegram استفاده می‌کند که در کلاینت‌های فعلی خوانا هستند: پررنگ، کج، پیوندها، کد، متن‌های پوشیده و نقل‌قول‌ها — نه بلوک‌های مختص محتوای غنی Bot API 10.2 (جدول‌های بومی، جزئیات، رسانه غنی و فرمول‌ها).

پیام‌های غنی Bot API 10.2 را فعال کنید:

{channels: {telegram: {  richMessages: true,},},}

هنگام فعال‌سازی: به عامل گفته می‌شود که پیام‌های غنی برای این ربات/حساب در دسترس‌اند (همراه با قرارداد پشتیبانی‌شده نگارش Markdown + جزیره HTML)؛ متن Markdown از طریق IR مربوط به Markdown در OpenClaw به‌صورت بلوک‌های غنی نوع‌دار Bot API 10.2 رندر می‌شود (عنوان‌ها، جدول‌ها، جزئیات، فهرست‌های بررسی، رسانه غنی، فرمول‌ها، نقشه‌ها و کلاژها)؛ زیرنویس‌های رسانه همچنان از زیرنویس HTML در Telegram استفاده می‌کنند (پیام‌های غنی جایگزین زیرنویس‌ها نمی‌شوند و زیرنویس‌ها حداکثر 1024 نویسه دارند).

این کار متن مدل را از نشانه‌های Markdown غنی Telegram دور نگه می‌دارد تا مقادیر پولی مانند $400-600K به‌عنوان ریاضی تجزیه نشوند. متن غنی طولانی به‌طور خودکار بر اساس محدودیت‌های Telegram تقسیم می‌شود. جدول‌هایی که از محدودیت 20 ستون عبور کنند به بلوک کد بازمی‌گردند.

پیش‌فرض: خاموش، برای سازگاری کلاینت — برخی کلاینت‌های فعلی Desktop، Web، Android و شخص ثالث، پیام‌های غنی پذیرفته‌شده را پشتیبانی‌نشده رندر می‌کنند. مگر آن‌که همه کلاینت‌های مورداستفاده با ربات بتوانند آن‌ها را رندر کنند، این گزینه را خاموش نگه دارید. /status نشان می‌دهد که پیام‌های غنی در نشست فعلی روشن هستند یا خاموش.

پیش‌نمایش پیوندها به‌طور پیش‌فرض روشن است. channels.telegram.linkPreview: false تشخیص خودکار موجودیت را برای متن غنی غیرفعال می‌کند.

منوی فرمان Telegram هنگام راه‌اندازی با setMyCommands ثبت می‌شود. commands.native: "auto" فرمان‌های بومی را برای Telegram فعال می‌کند.

ورودی‌های سفارشی را به منوی فرمان اضافه کنید:

{channels: {telegram: {  customCommands: [    { command: "backup", description: "پشتیبان‌گیری Git" },    { command: "generate", description: "ایجاد یک تصویر" },  ],},},}

قواعد: نام‌ها نرمال‌سازی می‌شوند (/ ابتدایی حذف و حروف کوچک می‌شوند)؛ الگوی معتبر a-z، 0-9، _، طول 1-32؛ فرمان‌های سفارشی نمی‌توانند فرمان‌های بومی را بازنویسی کنند؛ تعارض‌ها/تکراری‌ها رد و ثبت می‌شوند.

فرمان‌های سفارشی فقط ورودی‌های منو هستند — رفتار را به‌طور خودکار پیاده‌سازی نمی‌کنند. فرمان‌های Plugin/skill حتی اگر در منوی Telegram نمایش داده نشوند، همچنان می‌توانند هنگام تایپ کار کنند. اگر فرمان‌های بومی غیرفعال باشند، فرمان‌های داخلی حذف می‌شوند؛ فرمان‌های سفارشی/Plugin ممکن است در صورت پیکربندی همچنان ثبت شوند.

خطاهای رایج راه‌اندازی:

• setMyCommands failed همراه با BOT_COMMANDS_TOO_MUCH پس از تلاش مجدد برای کوتاه‌سازی، به این معناست که منو همچنان سرریز می‌شود؛ تعداد فرمان‌های 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

اگر دستگاهی با جزئیات احراز هویت تغییریافته (نقش، دامنه‌ها، کلید عمومی) دوباره تلاش کند، درخواست در انتظار قبلی با یک requestId جدید جایگزین می‌شود؛ پیش از تأیید، /pair pending را دوباره اجرا کنید.

جزئیات بیشتر: جفت‌سازی.

دامنه صفحه‌کلید درون‌خطی را پیکربندی کنید:

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

بازنویسی به‌ازای هر حساب:

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

دامنه‌ها: off، dm، group، all، allowlist (پیش‌فرض). مقدار قدیمی capabilities: ["inlineButtons"] به "all" نگاشت می‌شود.

نمونه کنش پیام:

{action: "send",channel: "telegram",to: "123456789",message: "یک گزینه انتخاب کنید:",buttons: [[  { text: "بله", callback_data: "yes" },  { text: "خیر", callback_data: "no" },],[{ text: "لغو", callback_data: "cancel" }],],}

نمونه دکمه Mini App:

{action: "send",channel: "telegram",to: "123456789",message: "باز کردن برنامه:",presentation: {blocks: [  {    type: "buttons",    buttons: [{ label: "راه‌اندازی", web_app: { url: "https://example.com/app" } }],  },],},}

دکمه‌های web_app فقط در چت‌های خصوصی میان کاربر و ربات کار می‌کنند.

کلیک‌های بازخوانی که هیچ کنترل‌کننده تعاملی ثبت‌شده Plugin آن‌ها را دریافت نکرده باشد، به‌صورت متن به عامل ارسال می‌شوند: callback_data: <value>.

کنش‌ها:

• sendMessage (to، content، mediaUrl اختیاری، replyToMessageId، messageThreadId)
• react (chatId، messageId، emoji)
• deleteMessage (chatId، messageId)
• editMessage (chatId، messageId، content یا caption، دکمه‌های درون‌خطی اختیاری presentation؛ ویرایش‌های صرفاً مربوط به دکمه، نشانه‌گذاری پاسخ را به‌روزرسانی می‌کنند)
• createForumTopic (chatId، name، iconColor اختیاری، iconCustomEmojiId)

نام‌های مستعار کاربردپسند: send، react، delete، edit، sticker، sticker-search، topic-create.

کنترل دسترسی: channels.telegram.actions.sendMessage، deleteMessage، reactions، sticker (پیش‌فرض: غیرفعال). edit، createForumTopic و editForumTopic به‌طور پیش‌فرض فعال‌اند و کلید اختصاصی ندارند. ارسال‌های زمان اجرا از تصویر لحظه‌ای فعال پیکربندی/اسرار در هنگام راه‌اندازی یا بارگذاری مجدد استفاده می‌کنند؛ بنابراین مسیرهای کنش برای هر ارسال، مقادیر SecretRef را دوباره تفکیک نمی‌کنند.

معنای حذف واکنش: /tools/reactions.

برچسب‌های صریح رشته‌بندی پاسخ در خروجی تولیدشده:

• [[reply_to_current]] — به پیام آغازگر پاسخ می‌دهد
• [[reply_to:<id>]] — به یک شناسه پیام مشخص پاسخ می‌دهد

channels.telegram.replyToMode: off (پیش‌فرض)، first، all.

وقتی رشته‌بندی پاسخ فعال باشد و متن/شرح اصلی در دسترس باشد، OpenClaw به‌طور خودکار یک گزیده نقل‌قول بومی اضافه می‌کند. 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 فقط مختص موضوع است و از پیش‌فرض‌های گروه ارث‌بری نمی‌کند. topics."*" پیش‌فرض‌های همه موضوعات آن گروه را تعیین می‌کند؛ شناسه‌های دقیق موضوع همچنان بر "*" اولویت دارند.

مسیریابی عامل به‌ازای هر موضوع: هر موضوع می‌تواند از طریق 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 را از طریق اتصال‌های نوع‌دار سطح بالا سنجاق کنند (bindings[] همراه با type: "acp"، match.channel: "telegram"، peer.kind: "group" و یک شناسه مقید به موضوع مانند -1001234567890:topic:42). در حال حاضر دامنه آن به موضوعات انجمن در گروه‌ها/ابرگروه‌ها محدود است. عامل‌های ACP را ببینید.

ایجاد ACP متصل به رشته از گفت‌وگو: /acp spawn <agent> --thread here|auto موضوع فعلی را به یک نشست ACP جدید متصل می‌کند؛ پیگیری‌ها مستقیماً به آنجا مسیریابی می‌شوند و OpenClaw تأیید ایجاد را در همان موضوع سنجاق می‌کند. با session.threadBindings.spawnSessions کنترل می‌شود (پیش‌فرض: true).

زمینه قالب، MessageThreadId و IsForum را ارائه می‌کند. گفت‌وگوهای پیام مستقیم با message_thread_id فراداده پاسخ را نگه می‌دارند، اما فقط زمانی از کلیدهای نشست آگاه از رشته استفاده می‌کنند که getMe در Telegram مقدار has_topics_enabled: true را گزارش کند. بازنویسی‌های منسوخ dm.threadReplies و direct.*.threadReplies حذف شده‌اند؛ حالت رشته‌ای BotFather تنها منبع حقیقت است. برای حذف کلیدهای پیکربندی قدیمی، openclaw doctor --fix را اجرا کنید.

پیام‌های صوتی

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

مکان‌ها و محل‌ها

از کنش موجود send همراه با یک شیء مستقل location استفاده کنید. مختصات، یک سنجاق بومی ارسال می‌کنند؛ افزودن هر دو name و address یک کارت بومی محل ارسال می‌کند. ارسال مکان را نمی‌توان با متن پیام یا رسانه ترکیب کرد.

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

استیکرها

ورودی: WEBP ایستا بارگیری و پردازش می‌شود (جای‌نگهدار <media:sticker>)؛ TGS متحرک و WEBM ویدئویی نادیده گرفته می‌شوند.

فیلدهای زمینه استیکر: Sticker.emoji، Sticker.setName، Sticker.fileId، Sticker.fileUniqueId، Sticker.cachedDescription. توضیحات در وضعیت Plugin مبتنی بر SQLite متعلق به OpenClaw ذخیره موقت می‌شوند تا فراخوانی‌های تکراری بینایی کاهش یابند.

کنش‌های استیکر را فعال کنید:

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

ارسال:

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

جست‌وجوی استیکرهای ذخیره‌شده در حافظه نهان:

{action: "sticker-search",channel: "telegram",query: "گربه در حال دست تکان دادن",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 برای polling/webhook به‌طور خودکار شامل message_reaction می‌شود.

ackReaction هنگامی که OpenClaw یک پیام ورودی را پردازش می‌کند، یک ایموجی تأیید دریافت ارسال می‌کند. messages.ackReactionScope تعیین می‌کند که چه زمانی ارسال شود.

ترتیب تفکیک ایموجی:

• channels.telegram.accounts.<accountId>.ackReaction
• channels.telegram.ackReaction
• messages.ackReaction
• ایموجی جایگزین هویت عامل (agents.entries.*.identity.emoji، وگرنه "👀")

Telegram انتظار یک ایموجی یونیکد دارد (برای مثال "👀")؛ برای غیرفعال‌کردن واکنش برای یک کانال یا حساب، از "" استفاده کنید.

دامنه (messages.ackReactionScope، پیش‌فرض "group-mentions"؛ در حال حاضر بدون بازنویسی مختص حساب Telegram یا کانال Telegram):

all (پیام‌های مستقیم + گروه‌ها، شامل رویدادهای محیطی اتاق)، direct (فقط پیام‌های مستقیم)، group-all (همه پیام‌های گروهی به‌جز رویدادهای محیطی اتاق، بدون پیام مستقیم)، group-mentions (گروه‌ها زمانی که به ربات اشاره می‌شود؛ بدون پیام مستقیم — پیش‌فرض)، off / none (غیرفعال).

نوشتن پیکربندی کانال به‌طور پیش‌فرض فعال است (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 اختیاری (پیش‌فرض /telegram-webhook)، webhookHost (پیش‌فرض 127.0.0.1)، webhookPort (پیش‌فرض 8787)، webhookCertPath (گواهی خودامضاشده PEM برای پیکربندی‌های دارای IP مستقیم یا بدون دامنه).

در حالت نظرسنجی طولانی، OpenClaw نشان‌گذاری راه‌اندازی مجدد خود را تنها پس از توزیع موفق یک به‌روزرسانی پایدار می‌کند؛ یک کنترل‌کننده ناموفق، آن به‌روزرسانی را در همان فرایند قابل تلاش مجدد نگه می‌دارد و آن را تکمیل‌شده علامت نمی‌زند.

شنونده محلی به‌طور پیش‌فرض به 127.0.0.1:8787 متصل می‌شود. برای ورودی عمومی، یک پروکسی معکوس جلوی درگاه محلی قرار دهید یا webhookHost: "0.0.0.0" را آگاهانه تنظیم کنید.

حالت Webhook محافظ‌های درخواست، توکن محرمانه Telegram و بدنه JSON را اعتبارسنجی می‌کند، سپس پیش از بازگرداندن یک 200 خالی، به‌روزرسانی را در صف ورودی پایدار خود ثبت می‌کند. پذیرش پایدار موفق شامل x-openclaw-delivery-accepted: durable است؛ پاسخ‌های سلامت، مسیریابی، احراز هویت، اعتبارسنجی و خطای ذخیره‌سازی این سرآیند را حذف می‌کنند. پروکسی‌های معکوس و کنترل‌کننده‌های میزبان می‌توانند این سرآیند را الزامی کنند تا پذیرش OpenClaw را از یک 200 خالی عمومی تشخیص دهند، بدون اینکه پذیرش را از زمان‌بندی پاسخ استنباط کنند.

پس از نوشتن پایدار، OpenClaw به‌روزرسانی‌ها را از طریق تخلیه ورودی کانال هسته مطالبه و پردازش می‌کند (مسیرهای به‌ازای هر گفت‌وگو/هر موضوع، تکمیل در زمان پذیرش نوبت، مهلت توقف پیش از پذیرش). نوبت‌های کند عامل، ACK تحویل Telegram را نگه نمی‌دارند.

• channels.telegram.textChunkLimit به‌طور پیش‌فرض 4000 است؛ streaming.chunkMode="newline" پیش از تقسیم بر اساس طول، مرزهای بندها (خطوط خالی) را ترجیح می‌دهد.
• channels.telegram.mediaMaxMb (پیش‌فرض 100) اندازه رسانه‌های ورودی و خروجی را محدود می‌کند.
• تاریخچه بافت گروه از 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.

مقصدهای ارسال در 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"

نظرسنجی‌ها از 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:). ‏--poll-option بین 2 تا 12 بار تکرار می‌شود (سقف گزینه‌های Telegram).

ارسال در Telegram همچنین از --presentation با بلوک‌های buttons برای صفحه‌کلیدهای درون‌خطی (وقتی channels.telegram.capabilities.inlineButtons آن را مجاز می‌داند)، --pin یا --delivery '{"pin":true}' برای درخواست تحویل سنجاق‌شده در صورتی که ربات بتواند در آن چت پیام را سنجاق کند، و --force-document برای ارسال تصاویر، GIFها و ویدئوهای خروجی به‌صورت سند به‌جای بارگذاری فشرده/متحرک/ویدئویی پشتیبانی می‌کند.

محدودسازی کنش‌ها: channels.telegram.actions.sendMessage=false همه پیام‌های خروجی، از جمله نظرسنجی‌ها، را غیرفعال می‌کند؛ channels.telegram.actions.poll=false ایجاد نظرسنجی را غیرفعال می‌کند، اما ارسال‌های عادی را فعال نگه می‌دارد.

Telegram از تأیید اجرای دستور در پیام‌های خصوصی تأییدکنندگان پشتیبانی می‌کند و می‌تواند به‌صورت اختیاری درخواست‌ها را در چت یا موضوع مبدأ ارسال کند. تأییدکنندگان باید شناسه‌های عددی کاربر Telegram باشند.

• channels.telegram.execApprovals.enabled ("auto" هنگامی فعال می‌شود که دست‌کم یک تأییدکننده قابل شناسایی باشد)
• 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/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 دوباره استفاده می‌کند تا اجراکننده پیش از نخستین getUpdates به getMe دومی نیاز نداشته باشد.
• اگر deleteWebhook هنگام راه‌اندازی نظرسنجی با خطای گذرای شبکه شکست بخورد، OpenClaw به‌جای انجام فراخوانی کنترلی دیگری پیش از نظرسنجی، وارد نظرسنجی طولانی می‌شود. در این صورت Webhook همچنان فعال به‌شکل تداخل getUpdates نمایان می‌شود؛ OpenClaw انتقال را بازسازی می‌کند و پاک‌سازی Webhook را دوباره امتحان می‌کند.
• Polling stall detected در گزارش‌ها یعنی OpenClaw به‌طور پیش‌فرض پس از 120 ثانیه بدون تکمیل زنده‌بودن نظرسنجی طولانی، نظرسنجی را از نو آغاز و انتقال را بازسازی می‌کند.
• openclaw channels status --probe و openclaw doctor هنگامی هشدار می‌دهند که یک حساب نظرسنجی در حال اجرا پس از مهلت راه‌اندازی getUpdates را تکمیل نکرده باشد، یک حساب Webhook در حال اجرا پس از مهلت راه‌اندازی setWebhook را تکمیل نکرده باشد، یا آخرین فعالیت موفق انتقال نظرسنجی کهنه شده باشد.
• 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 ناپایدار، فراخوانی‌های API مربوط به Telegram را از طریق پروکسی هدایت کنید:

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 یا شفاف مورداعتماد هنگام دانلود رسانه، 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 Adig +short api.telegram.org AAAA