Telegram

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

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

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

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

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

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

• /setjoingroups برای اجازه/رد کردن افزودن به گروه
• /setprivacy برای رفتار دیده‌شدن در گروه

OpenClaw می‌تواند پاسخ‌های جزئی را به‌صورت بلادرنگ stream کند:

• چت‌های مستقیم: پیام preview + editMessageText
• گروه‌ها/موضوع‌ها: پیام preview + editMessageText

نیازمندی:

• channels.telegram.streaming برابر off | partial | block | progress است (پیش‌فرض: partial)
• progress یک پیش‌نویس وضعیت قابل ویرایش برای پیشرفت ابزار نگه می‌دارد، آن را هنگام تکمیل پاک می‌کند، و پاسخ نهایی را به‌عنوان پیام عادی می‌فرستد
• streaming.preview.toolProgress کنترل می‌کند که آیا به‌روزرسانی‌های ابزار/پیشرفت از همان پیام preview ویرایش‌شده دوباره استفاده کنند یا نه (پیش‌فرض: true وقتی preview streaming فعال است)
• streaming.preview.commandText جزئیات فرمان/اجرا را داخل آن خطوط پیشرفت ابزار کنترل می‌کند: raw (پیش‌فرض، رفتار منتشرشده را حفظ می‌کند) یا status (فقط برچسب ابزار)
• channels.telegram.streamMode قدیمی و مقادیر بولی streaming تشخیص داده می‌شوند؛ openclaw doctor --fix را اجرا کنید تا آن‌ها را به channels.telegram.streaming.mode مهاجرت دهید

به‌روزرسانی‌های preview پیشرفت ابزار، خطوط وضعیت کوتاهی هستند که هنگام اجرای ابزارها نمایش داده می‌شوند، برای مثال اجرای فرمان، خواندن فایل، به‌روزرسانی‌های برنامه‌ریزی، یا خلاصه‌های patch. Telegram این‌ها را به‌طور پیش‌فرض فعال نگه می‌دارد تا با رفتار منتشرشدهٔ OpenClaw از v2026.4.22 و بعد از آن همخوان باشد. برای نگه‌داشتن preview ویرایش‌شده برای متن پاسخ اما پنهان کردن خطوط پیشرفت ابزار، این را تنظیم کنید:

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

برای پاسخ‌های فقط متنی:

• پیش‌نمایش‌های کوتاه DM/گروه/موضوع: OpenClaw همان پیام پیش‌نمایش را نگه می‌دارد و ویرایش نهایی را در همان‌جا انجام می‌دهد
• خروجی‌های نهایی متنی بلند که به چند پیام Telegram تقسیم می‌شوند، در صورت امکان از پیش‌نمایش موجود به‌عنوان نخستین قطعه نهایی استفاده می‌کنند و سپس فقط قطعه‌های باقی‌مانده را می‌فرستند
• خروجی‌های نهایی حالت پیشرفت، پیش‌نویس وضعیت را پاک می‌کنند و به‌جای ویرایش پیش‌نویس به پاسخ، از تحویل نهایی معمول استفاده می‌کنند
• اگر ویرایش نهایی پیش از تأیید متن کامل‌شده شکست بخورد، OpenClaw از تحویل نهایی معمول استفاده می‌کند و پیش‌نمایش کهنه را پاک‌سازی می‌کند

برای پاسخ‌های پیچیده (برای مثال payloadهای رسانه‌ای)، OpenClaw به تحویل نهایی معمول برمی‌گردد و سپس پیام پیش‌نمایش را پاک‌سازی می‌کند.

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

جریان استدلال فقط برای Telegram:

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

متن خروجی از parse_mode: "HTML" در Telegram استفاده می‌کند.

• متن شبیه Markdown به HTML امن برای Telegram رندر می‌شود.
• HTML خام مدل escape می‌شود تا شکست‌های parse در Telegram کاهش یابد.
• اگر Telegram HTML پردازش‌شده را رد کند، OpenClaw دوباره به‌صورت متن ساده تلاش می‌کند.

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

ثبت منوی دستور Telegram هنگام راه‌اندازی با setMyCommands انجام می‌شود.

پیش‌فرض‌های دستور بومی:

• 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 نشان داده نشوند

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

شکست‌های رایج راه‌اندازی:

• setMyCommands failed با BOT_COMMANDS_TOO_MUCH یعنی منوی Telegram پس از کوتاه‌سازی همچنان از حد مجاز گذشته است؛ دستورهای Plugin/Skills/سفارشی را کاهش دهید یا channels.telegram.commands.native را غیرفعال کنید.
• شکست deleteWebhook، deleteMyCommands یا setMyCommands با 404: Not Found در حالی که دستورهای مستقیم Bot API با curl کار می‌کنند، می‌تواند به این معنی باشد که 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 مسدود شده است.

# دستورهای جفت‌سازی دستگاه (device-pair Plugin)

وقتی device-pair Plugin نصب شده باشد:

1. /pair کد راه‌اندازی تولید می‌کند
2. کد را در برنامه iOS جای‌گذاری کنید
3. /pair pending درخواست‌های در انتظار را فهرست می‌کند (شامل role/scopes)
4. درخواست را تأیید کنید:
   • /pair approve <requestId> برای تأیید صریح
   • /pair approve وقتی فقط یک درخواست در انتظار وجود دارد
   • /pair approve latest برای جدیدترین مورد

کد راه‌اندازی یک توکن bootstrap کوتاه‌عمر حمل می‌کند. تحویل داخلی bootstrap، توکن Node اصلی را در scopes: [] نگه می‌دارد؛ هر توکن operator واگذارشده به operator.approvals، operator.read، operator.talk.secrets و operator.write محدود می‌ماند. بررسی‌های scope در bootstrap دارای پیشوند نقش هستند، بنابراین آن allowlist مربوط به operator فقط درخواست‌های operator را برآورده می‌کند؛ نقش‌های غیر operator همچنان به scopeهایی زیر پیشوند نقش خودشان نیاز دارند.

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

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

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

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

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

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

محدوده‌ها:

• off
• dm
• group
• all
• allowlist (پیش‌فرض)

capabilities: ["inlineButtons"] قدیمی به inlineButtons: "all" نگاشت می‌شود.

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

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

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

کنش‌های ابزار Telegram شامل این موارد هستند:

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

کنش‌های پیام کانال aliasهای آسان‌کار ارائه می‌کنند (send، react، delete، edit، sticker، sticker-search، topic-create).

کنترل‌های محدودسازی:

• channels.telegram.actions.sendMessage
• channels.telegram.actions.deleteMessage
• channels.telegram.actions.reactions
• channels.telegram.actions.sticker (پیش‌فرض: غیرفعال)

توجه: edit و topic-create در حال حاضر به‌صورت پیش‌فرض فعال هستند و toggleهای جداگانه channels.telegram.actions.* ندارند. ارسال‌های زمان اجرا از تصویر لحظه‌ای فعال پیکربندی/اسرار (راه‌اندازی/بارگذاری مجدد) استفاده می‌کنند، بنابراین مسیرهای کنش برای هر ارسال، بازحل‌کردن موردی SecretRef انجام نمی‌دهند.

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

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

• [[reply_to_current]] به پیام محرک پاسخ می‌دهد
• [[reply_to:<id>]] به یک شناسه پیام مشخص Telegram پاسخ می‌دهد

channels.telegram.replyToMode نحوه رسیدگی را کنترل می‌کند:

• off (پیش‌فرض)
• first
• all

وقتی رشته‌بندی پاسخ فعال باشد و متن یا caption اصلی Telegram در دسترس باشد، OpenClaw به‌طور خودکار یک excerpt نقل‌قول بومی Telegram را شامل می‌کند. 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 فقط مخصوص موضوع است و از پیش‌فرض‌های گروه ارث‌بری نمی‌کند.

مسیریابی عامل برای هر موضوع: هر موضوع می‌تواند با تنظیم agentId در پیکربندی موضوع، به عامل متفاوتی مسیریابی شود. این کار به هر موضوع، فضای کاری، حافظه و نشست ایزوله خودش را می‌دهد. مثال:

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

سپس هر موضوع کلید نشست خودش را دارد: agent:zu:telegram:group:-1001234567890:topic:3

اتصال پایدار موضوع ACP: موضوع‌های انجمن می‌توانند نشست‌های harness ACP را از طریق bindingهای ACP typed سطح بالا pin کنند (bindings[] با type: "acp" و match.channel: "telegram"، peer.kind: "group" و یک شناسه واجد موضوع مثل -1001234567890:topic:42). در حال حاضر به موضوع‌های انجمن در گروه‌ها/ابرگروه‌ها محدود است. عامل‌های ACP را ببینید.

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

زمینه‌ی الگو MessageThreadId و IsForum را در دسترس قرار می‌دهد. گفت‌وگوهای DM با message_thread_id به‌طور پیش‌فرض مسیریابی DM و فراداده‌ی پاسخ را در نشست‌های تخت نگه می‌دارند؛ آن‌ها فقط وقتی از کلیدهای نشست آگاه از رشته استفاده می‌کنند که با threadReplies: "inbound"، threadReplies: "always"، requireTopic: true، یا پیکربندی topic مطابق تنظیم شده باشند. برای پیش‌فرض حساب از channels.telegram.dm.threadReplies در سطح بالا استفاده کنید، یا برای یک DM از direct.<chatId>.threadReplies.

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

Telegram بین یادداشت‌های صوتی و فایل‌های صوتی تمایز قائل می‌شود.

• پیش‌فرض: رفتار فایل صوتی
• برچسب [[audio_as_voice]] در پاسخ عامل برای اجبار به ارسال یادداشت صوتی
• رونوشت‌های یادداشت صوتی ورودی در زمینه‌ی عامل به‌صورت متن ماشین‌تولید و نامطمئن قاب‌بندی می‌شوند؛ تشخیص mention همچنان از رونوشت خام استفاده می‌کند، بنابراین پیام‌های صوتی محدودشده با mention همچنان کار می‌کنند.

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

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

یادداشت‌های ویدیویی از کپشن پشتیبانی نمی‌کنند؛ متن پیام ارائه‌شده جداگانه ارسال می‌شود.

# استیکرها

مدیریت استیکر ورودی:

• WEBP ایستا: دانلود و پردازش می‌شود (placeholder <media:sticker>)
• TGS متحرک: رد می‌شود
• WEBM ویدیویی: رد می‌شود

فیلدهای زمینه‌ی استیکر:

• Sticker.emoji
• Sticker.setName
• Sticker.fileId
• Sticker.fileUniqueId
• Sticker.cachedDescription

فایل کش استیکر:

• ~/.openclaw/telegram/sticker-cache.json

استیکرها یک‌بار توصیف می‌شوند (در صورت امکان) و برای کاهش فراخوانی‌های تکراری vision کش می‌شوند.

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

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

کنش ارسال استیکر:

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

جست‌وجوی استیکرهای کش‌شده:

{
action: "sticker-search",
channel: "telegram",
query: "cat waving",
limit: 5,
}

واکنش‌های Telegram به‌صورت به‌روزرسانی‌های message_reaction می‌رسند (جدا از payloadهای پیام).

وقتی فعال باشد، 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 عمومی گروه (:topic:1) مسیریابی می‌شوند، نه topic دقیق مبدأ

allowed_updates برای polling/webhook به‌طور خودکار شامل message_reaction است.

ackReaction هنگام پردازش یک پیام ورودی توسط OpenClaw یک ایموجی تأیید دریافت ارسال می‌کند.

ترتیب تفکیک:

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

نکته‌ها:

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

نوشتن پیکربندی کانال به‌طور پیش‌فرض فعال است (configWrites !== false).

نوشتن‌های تحریک‌شده توسط Telegram شامل موارد زیر است:

• رویدادهای مهاجرت گروه (migrate_to_chat_id) برای به‌روزرسانی channels.telegram.groups
• /config set و /config unset (نیازمند فعال‌سازی فرمان)

غیرفعال‌سازی:

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

پیش‌فرض long polling است. برای حالت webhook، channels.telegram.webhookUrl و channels.telegram.webhookSecret را تنظیم کنید؛ webhookPath، webhookHost، webhookPort اختیاری هستند (پیش‌فرض‌ها /telegram-webhook، 127.0.0.1، 8787).

در حالت long-polling، OpenClaw واترمارک راه‌اندازی مجدد خود را فقط پس از توزیع موفق یک به‌روزرسانی پایدار می‌کند. اگر یک handler شکست بخورد، آن به‌روزرسانی در همان فرایند قابل تلاش دوباره باقی می‌ماند و برای dedupe راه‌اندازی مجدد به‌عنوان تکمیل‌شده نوشته نمی‌شود.

شنونده‌ی محلی به 127.0.0.1:8787 متصل می‌شود. برای ورودی عمومی، یا یک reverse proxy جلوی پورت محلی بگذارید یا عمداً webhookHost: "0.0.0.0" را تنظیم کنید.

حالت Webhook، guardهای درخواست، توکن محرمانه‌ی Telegram، و بدنه‌ی JSON را پیش از برگرداندن 200 به Telegram اعتبارسنجی می‌کند. سپس OpenClaw به‌روزرسانی را به‌صورت ناهمگام از همان مسیرهای بات به‌ازای هر گفت‌وگو/هر topic که long polling استفاده می‌کند پردازش می‌کند، بنابراین نوبت‌های کند عامل ACK تحویل Telegram را نگه نمی‌دارند.

• پیش‌فرض channels.telegram.textChunkLimit برابر 4000 است.
• channels.telegram.chunkMode="newline" پیش از تقسیم بر اساس طول، مرزهای پاراگراف (خطوط خالی) را ترجیح می‌دهد.
• channels.telegram.mediaMaxMb (پیش‌فرض 100) اندازه‌ی رسانه‌ی ورودی و خروجی Telegram را محدود می‌کند.
• channels.telegram.mediaGroupFlushMs (پیش‌فرض 500) کنترل می‌کند آلبوم‌ها/گروه‌های رسانه‌ای Telegram چه مدت buffer شوند پیش از آنکه OpenClaw آن‌ها را به‌عنوان یک پیام ورودی توزیع کند. اگر بخش‌های آلبوم دیر می‌رسند آن را افزایش دهید؛ برای کاهش تأخیر پاسخ آلبوم آن را کاهش دهید.
• channels.telegram.timeoutSeconds زمان انتظار کلاینت API تلگرام را بازنویسی می‌کند (اگر تنظیم نشده باشد، پیش‌فرض grammY اعمال می‌شود). کلاینت‌های بات مقدارهای پیکربندی‌شده‌ی کمتر از guard درخواست ۶۰ ثانیه‌ای متن/typing خروجی را clamp می‌کنند تا grammY تحویل پاسخ قابل مشاهده را پیش از اجرای guard انتقال و fallback در OpenClaw قطع نکند. long polling همچنان از guard درخواست ۴۵ ثانیه‌ای getUpdates استفاده می‌کند تا pollهای idle بی‌پایان رها نشوند.
• پیش‌فرض channels.telegram.pollingStallThresholdMs برابر 120000 است؛ فقط برای راه‌اندازی‌های مجدد false-positive ناشی از توقف polling، بین 30000 و 600000 تنظیم کنید.
• تاریخچه‌ی زمینه‌ی گروه از channels.telegram.historyLimit یا messages.groupChat.historyLimit استفاده می‌کند (پیش‌فرض 50)؛ 0 غیرفعال می‌کند.
• زمینه‌ی تکمیلی reply/quote/forward در حال حاضر همان‌طور که دریافت شده پاس داده می‌شود.
• allowlistهای Telegram عمدتاً کنترل می‌کنند چه کسی می‌تواند عامل را تحریک کند، نه یک مرز کامل حذف زمینه‌ی تکمیلی.
• کنترل‌های تاریخچه‌ی DM:
  • channels.telegram.dmHistoryLimit
  • channels.telegram.dms["<user_id>"].historyLimit
• پیکربندی channels.telegram.retry برای خطاهای API خروجی قابل بازیابی روی helperهای ارسال Telegram (CLI/tools/actions) اعمال می‌شود. تحویل پاسخ نهایی ورودی نیز برای شکست‌های pre-connect در Telegram از تلاش دوباره‌ی safe-send محدود استفاده می‌کند، اما envelopeهای شبکه‌ی مبهم پس از ارسال را که ممکن است پیام‌های قابل مشاهده را تکراری کنند دوباره تلاش نمی‌کند.

هدف‌های ارسال CLI و message-tool می‌توانند شناسه‌ی عددی گفت‌وگو، نام کاربری، یا هدف topic فوروم باشند:

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"

pollهای Telegram از openclaw message poll استفاده می‌کنند و از 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 فقط مخصوص Telegram:

• --poll-duration-seconds (5-600)
• --poll-anonymous
• --poll-public
• --thread-id برای topicهای فوروم (یا از هدف :topic: استفاده کنید)

ارسال Telegram همچنین پشتیبانی می‌کند از:

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

کنترل کنش:

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

Telegram از تأییدهای exec در DMهای تأییدکننده پشتیبانی می‌کند و می‌تواند به‌صورت اختیاری promptها را در گفت‌وگو یا topic مبدأ پست کند. تأییدکننده‌ها باید شناسه‌های عددی کاربر Telegram باشند.

مسیر پیکربندی:

• channels.telegram.execApprovals.enabled (وقتی حداقل یک تأییدکننده قابل تفکیک باشد خودکار فعال می‌شود)
• channels.telegram.execApprovals.approvers (به شناسه‌های عددی مالک از commands.ownerAllowFrom fallback می‌کند)
• channels.telegram.execApprovals.target: dm (پیش‌فرض) | channel | both
• agentFilter, sessionFilter

channels.telegram.allowFrom، groupAllowFrom، و defaultTo کنترل می‌کنند چه کسی می‌تواند با بات صحبت کند و پاسخ‌های عادی را کجا ارسال می‌کند. آن‌ها کسی را به تأییدکننده‌ی exec تبدیل نمی‌کنند. اولین جفت‌سازی DM تأییدشده وقتی هنوز مالک فرمانی وجود ندارد، commands.ownerAllowFrom را bootstrap می‌کند، بنابراین راه‌اندازی تک‌مالک همچنان بدون تکرار شناسه‌ها زیر execApprovals.approvers کار می‌کند.

تحویل کانال متن فرمان را در گفت‌وگو نشان می‌دهد؛ channel یا both را فقط در گروه‌ها/topicهای مورد اعتماد فعال کنید. وقتی prompt در یک topic فوروم قرار می‌گیرد، OpenClaw همان topic را برای prompt تأیید و پیگیری حفظ می‌کند. تأییدهای exec به‌طور پیش‌فرض پس از ۳۰ دقیقه منقضی می‌شوند.

دکمه‌های تأیید درون‌خطی نیز نیاز دارند channels.telegram.capabilities.inlineButtons سطح هدف (dm، group، یا all) را مجاز کند. شناسه‌های تأیید با پیشوند plugin: از طریق تأییدهای Plugin تفکیک می‌شوند؛ بقیه ابتدا از طریق تأییدهای exec تفکیک می‌شوند.

تأییدهای exec را ببینید.

• اگر requireMention=false باشد، حالت حریم خصوصی Telegram باید دید کامل را مجاز کند.
  • BotFather: /setprivacy -> غیرفعال‌سازی
  • سپس ربات را از گروه حذف کنید و دوباره اضافه کنید
• وقتی پیکربندی انتظار پیام‌های گروهی بدون منشن را دارد، openclaw channels status هشدار می‌دهد.
• openclaw channels status --probe می‌تواند شناسه‌های عددی صریح گروه را بررسی کند؛ wildcard "*" را نمی‌توان از نظر عضویت بررسی کرد.
• آزمون سریع نشست: /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 resolve می‌کنند؛ خروجی خراب IPv6 می‌تواند باعث شکست‌های متناوب API Telegram شود.
• اگر گزارش‌ها شامل TypeError: fetch failed یا Network request for 'getUpdates' failed! باشند، OpenClaw اکنون این موارد را به‌عنوان خطاهای شبکه قابل بازیابی دوباره تلاش می‌کند.
• هنگام راه‌اندازی polling، OpenClaw بررسی موفق راه‌اندازی getMe را برای grammY دوباره استفاده می‌کند تا اجراکننده پیش از اولین getUpdates به getMe دوم نیاز نداشته باشد.
• اگر deleteWebhook هنگام راه‌اندازی polling با خطای شبکه گذرا شکست بخورد، OpenClaw به‌جای انجام یک فراخوانی control-plane دیگر پیش از polling، وارد long polling می‌شود. webhook همچنان فعال به‌صورت تعارض getUpdates ظاهر می‌شود؛ سپس OpenClaw انتقال Telegram را بازسازی می‌کند و پاک‌سازی webhook را دوباره تلاش می‌کند.
• اگر سوکت‌های Telegram در یک چرخه ثابت کوتاه بازیافت می‌شوند، مقدار پایین channels.telegram.timeoutSeconds را بررسی کنید؛ کلاینت‌های ربات مقادیر پیکربندی‌شده پایین‌تر از محافظ‌های درخواست خروجی و getUpdates را محدود می‌کنند، اما نسخه‌های قدیمی‌تر ممکن بود وقتی این مقدار پایین‌تر از آن محافظ‌ها تنظیم شده بود، هر poll یا پاسخ را متوقف کنند.
• اگر گزارش‌ها شامل Polling stall detected باشند، OpenClaw به‌صورت پیش‌فرض پس از 120 ثانیه بدون liveness تکمیل‌شده long-poll، polling را دوباره راه‌اندازی می‌کند و انتقال Telegram را بازسازی می‌کند.
• openclaw channels status --probe و openclaw doctor زمانی هشدار می‌دهند که یک حساب polling در حال اجرا پس از مهلت راه‌اندازی getUpdates را تکمیل نکرده باشد، یک حساب webhook در حال اجرا پس از مهلت راه‌اندازی setWebhook را تکمیل نکرده باشد، یا آخرین فعالیت موفق انتقال polling قدیمی شده باشد.
• فقط زمانی channels.telegram.pollingStallThresholdMs را افزایش دهید که فراخوانی‌های طولانی‌مدت getUpdates سالم هستند اما میزبان شما همچنان راه‌اندازی‌های مجدد polling-stall کاذب گزارش می‌کند. توقف‌های پایدار معمولا به مشکلات proxy، DNS، IPv6 یا خروجی TLS بین میزبان و api.telegram.org اشاره دارند.
• Telegram همچنین env پروکسی فرایند را برای انتقال Bot API رعایت می‌کند، از جمله HTTP_PROXY، HTTPS_PROXY، ALL_PROXY و گونه‌های حروف کوچک آن‌ها. NO_PROXY / no_proxy همچنان می‌تواند api.telegram.org را دور بزند.
• اگر پروکسی مدیریت‌شده OpenClaw از طریق OPENCLAW_PROXY_URL برای یک محیط سرویس پیکربندی شده باشد و env پروکسی استانداردی وجود نداشته باشد، Telegram نیز از همان URL برای انتقال Bot API استفاده می‌کند.
• در میزبان‌های VPS با خروجی مستقیم/TLS ناپایدار، فراخوانی‌های API Telegram را از طریق 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

• پاسخ‌های بازه benchmark در RFC 2544‏ (198.18.0.0/15) به‌صورت پیش‌فرض از قبل برای دانلودهای رسانه Telegram مجاز هستند. اگر یک fake-IP قابل اعتماد یا پروکسی شفاف هنگام دانلود رسانه، api.telegram.org را به آدرس خصوصی/داخلی/با کاربرد ویژه دیگری بازنویسی می‌کند، می‌توانید برای دورزدن فقط مخصوص Telegram opt in کنید:

channels:
telegram:
network:
  dangerouslyAllowPrivateNetwork: true

• همین opt-in برای هر حساب نیز در channels.telegram.accounts.<accountId>.network.dangerouslyAllowPrivateNetwork در دسترس است.
• اگر پروکسی شما میزبان‌های رسانه Telegram را به 198.18.x.x resolve می‌کند، ابتدا پرچم خطرناک را خاموش بگذارید. رسانه Telegram از قبل به‌صورت پیش‌فرض بازه benchmark در 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