--- read_when: - کار روی قابلیت‌ها یا Webhookهای Telegram summary: وضعیت پشتیبانی، قابلیت‌ها و پیکربندی ربات Telegram title: Telegram x-i18n: generated_at: "2026-07-16T16:12:36Z" model: gpt-5.6 postprocess_version: locale-links-v1 prompt_version: 32 provider: openai source_hash: 51c155afeb147b92a55f181be269ce13c4fd6b609a94d680cd7e091cd4a7c236 source_path: channels/telegram.md workflow: 16 --- آماده بهره‌برداری برای پیام‌های خصوصی و گروه‌های ربات از طریق grammY. Long polling روش انتقال پیش‌فرض است؛ حالت Webhook اختیاری است. سیاست پیش‌فرض پیام خصوصی برای Telegram، جفت‌سازی است. راهنماهای تشخیص و رفع اشکال میان‌کانالی. الگوها و نمونه‌های کامل پیکربندی کانال. ## راه‌اندازی سریع هر دو روش در نهایت توکنی ارائه می‌دهند که باید در OpenClaw وارد کنید — یکی را انتخاب کنید: - **روش گفت‌وگو**: Telegram را باز کنید، با **@BotFather** گفت‌وگو کنید (تأیید کنید که شناسه دقیقاً `@BotFather` است)، `/newbot` را اجرا کنید، دستورالعمل‌ها را دنبال کنید و توکن را ذخیره کنید. - **روش وب**: [برنامه وب BotFather](https://t.me/BotFather?startapp) را باز کنید — این برنامه در همه کلاینت‌های Telegram، از جمله [web.telegram.org](https://web.telegram.org)، اجرا می‌شود — ربات را در رابط کاربری ایجاد کنید و توکن آن را کپی کنید. ```json5 { channels: { telegram: { enabled: true, botToken: "123:abc", dmPolicy: "pairing", groups: { "*": { requireMention: true } }, }, }, } ``` جایگزین محیطی: `TELEGRAM_BOT_TOKEN` (فقط حساب پیش‌فرض؛ حساب‌های نام‌گذاری‌شده باید از `botToken` یا `tokenFile` استفاده کنند). Telegram از `openclaw channels login telegram` استفاده **نمی‌کند**؛ توکن را در پیکربندی/محیط تنظیم کنید، سپس Gateway را راه‌اندازی کنید. ```bash openclaw gateway openclaw pairing list telegram openclaw pairing approve telegram ``` کدهای جفت‌سازی پس از 1 ساعت منقضی می‌شوند. ربات را به گروه خود اضافه کنید، سپس دو شناسه موردنیاز برای دسترسی گروه را به‌دست آورید: - شناسه کاربری Telegram شما، برای `allowFrom` / `groupAllowFrom` - شناسه گفت‌وگوی گروه Telegram، به‌عنوان کلید زیر `channels.telegram.groups` شناسه گفت‌وگوی گروه را از `openclaw logs --follow`، یک ربات شناسه پیام‌های هدایت‌شده، یا `getUpdates` در Bot API دریافت کنید. پس از مجاز شدن گروه، `/whoami@` شناسه‌های کاربر و گروه را تأیید می‌کند. شناسه‌های منفی ابرگروه که با `-100` شروع می‌شوند، شناسه گفت‌وگوی گروه هستند. آن‌ها باید زیر `channels.telegram.groups` قرار گیرند، نه `groupAllowFrom`. تفکیک توکن با توجه به حساب انجام می‌شود: `tokenFile` بر `botToken` و آن نیز بر محیط اولویت دارد، و پیکربندی همیشه بر `TELEGRAM_BOT_TOKEN` اولویت دارد (که فقط برای حساب پیش‌فرض تفکیک می‌شود). پس از راه‌اندازی موفق، OpenClaw هویت ربات را تا 24 ساعت در حافظه نهان نگه می‌دارد تا در راه‌اندازی‌های مجدد، فراخوانی اضافی `getMe` انجام نشود؛ تغییر یا حذف توکن این حافظه نهان را پاک می‌کند. ## تنظیمات سمت Telegram ربات‌های Telegram به‌طور پیش‌فرض از **Privacy Mode** استفاده می‌کنند که پیام‌های گروهی دریافتی آن‌ها را محدود می‌کند. برای مشاهده همه پیام‌های گروه، یکی از این کارها را انجام دهید: - حالت حریم خصوصی را از طریق `/setprivacy` غیرفعال کنید، یا - ربات را مدیر گروه کنید. پس از تغییر حالت حریم خصوصی، ربات را در هر گروه حذف و دوباره اضافه کنید تا Telegram تغییر را اعمال کند. وضعیت مدیریت در تنظیمات گروه Telegram کنترل می‌شود. ربات‌های مدیر همه پیام‌های گروه را دریافت می‌کنند که برای رفتار همیشه‌فعال در گروه مفید است. - `/setjoingroups` — اجازه/جلوگیری از افزودن به گروه‌ها - `/setprivacy` — رفتار مشاهده‌پذیری در گروه اگر رابط کاربری را به فرمان‌های گفت‌وگو ترجیح می‌دهید، همین تنظیمات در [برنامه وب BotFather](https://t.me/BotFather?startapp) نیز در دسترس هستند. ## Mini App داشبورد برای باز کردن داشبورد OpenClaw درون Telegram، `/dashboard` را در یک پیام خصوصی با ربات اجرا کنید. الزامات: - `gateway.tailscale.mode: "serve"` یا `"funnel"` برای URL منتشرشده HTTPS مربوط به Mini App. - شناسه کاربری عددی Telegram شما باید در `allowFrom` مؤثر حساب انتخاب‌شده یا در `commands.ownerAllowFrom` باشد. - از پیام خصوصی استفاده کنید. در گروه‌ها، `/dashboard` با `open this in a DM with the bot` پاسخ می‌دهد و هیچ دکمه‌ای ارسال نمی‌کند. - نصب‌های Docker: حالت‌های Serve/Funnel مستلزم آن هستند که Gateway در کنار `tailscaled` به loopback متصل شود؛ شبکه‌سازی bridge با پورت‌های منتشرشده نمی‌تواند این شرط را برآورده کند. کانتینر Gateway را با `network_mode: host` اجرا کنید و سوکت `tailscaled` میزبان (`/var/run/tailscale`) به‌همراه CLI مربوط به `tailscale` را درون کانتینر mount کنید. Mini App یک مسیر v1 مختص Tailscale است و از iframe در Telegram Web پشتیبانی نمی‌کند. ## کنترل دسترسی و فعال‌سازی ### هویت ربات در گروه در گروه‌ها و موضوعات انجمن، اشاره صریح به شناسه پیکربندی‌شده ربات (برای مثال `@my_bot`) عامل انتخاب‌شده OpenClaw را مخاطب قرار می‌دهد، حتی اگر نام شخصیت عامل با نام کاربری Telegram متفاوت باشد. سیاست سکوت گروه همچنان برای ترافیک نامرتبط اعمال می‌شود، اما خود شناسه ربات هرگز «شخص دیگری» محسوب نمی‌شود. `channels.telegram.dmPolicy` دسترسی پیام خصوصی را کنترل می‌کند: - `pairing` (پیش‌فرض) - `allowlist` (به حداقل یک شناسه فرستنده در `allowFrom` نیاز دارد) - `open` (نیازمند آن است که `allowFrom` شامل `"*"` باشد) - `disabled` `dmPolicy: "open"` همراه با `allowFrom: ["*"]` به هر حساب Telegram که نام کاربری ربات را پیدا یا حدس بزند، اجازه می‌دهد به ربات فرمان دهد. فقط برای ربات‌هایی که عمداً عمومی هستند و ابزارهایشان به‌شدت محدود شده است از آن استفاده کنید؛ ربات‌های تک‌مالک باید از `allowlist` همراه با شناسه‌های عددی کاربر استفاده کنند. `channels.telegram.allowFrom` شناسه‌های عددی کاربران Telegram را می‌پذیرد. پیشوندهای `telegram:` / `tg:` پذیرفته و نرمال‌سازی می‌شوند. در پیکربندی‌های چندحسابی، `channels.telegram.allowFrom` محدودکننده در سطح بالا یک مرز ایمنی است: `allowFrom: ["*"]` در سطح حساب، آن حساب را عمومی نمی‌کند، مگر اینکه فهرست مجاز مؤثر پس از ادغام همچنان شامل یک نویسه عام صریح باشد. `dmPolicy: "allowlist"` همراه با `allowFrom` خالی، همه پیام‌های خصوصی را مسدود می‌کند و اعتبارسنجی پیکربندی آن را رد می‌کند. راه‌اندازی فقط شناسه‌های عددی کاربر را درخواست می‌کند. اگر پیکربندی شما ورودی‌های فهرست مجاز `@username` از یک راه‌اندازی قدیمی دارد، `openclaw doctor --fix` را اجرا کنید تا آن‌ها را به شناسه‌های عددی تبدیل کند (تا حد امکان؛ نیازمند توکن ربات Telegram). اگر پیش‌تر به فایل‌های فهرست مجاز ذخیره‌گاه جفت‌سازی متکی بودید، `openclaw doctor --fix` می‌تواند ورودی‌ها را برای جریان‌های فهرست مجاز در `channels.telegram.allowFrom` بازیابی کند (برای مثال وقتی `dmPolicy: "allowlist"` هنوز هیچ شناسه صریحی ندارد). برای ربات‌های تک‌مالک، `dmPolicy: "allowlist"` همراه با شناسه‌های عددی صریح `allowFrom` را به اتکا به تأییدهای جفت‌سازی پیشین ترجیح دهید. ابهام رایج: تأیید جفت‌سازی پیام خصوصی به این معنا نیست که «این فرستنده در همه‌جا مجاز است». جفت‌سازی فقط دسترسی پیام خصوصی را اعطا می‌کند. اگر هنوز مالک فرمانی وجود نداشته باشد، نخستین جفت‌سازی تأییدشده همچنین `commands.ownerAllowFrom` را تنظیم می‌کند و برای فرمان‌های مختص مالک و تأیید اجرای فرمان‌ها یک حساب اپراتور صریح فراهم می‌کند. مجوز فرستنده در گروه همچنان از فهرست‌های مجاز صریح پیکربندی می‌آید. برای اینکه یک هویت هم برای پیام‌های خصوصی و هم برای فرمان‌های گروه مجاز باشد: شناسه کاربری عددی Telegram خود را در `channels.telegram.allowFrom` قرار دهید و برای فرمان‌های مختص مالک مطمئن شوید `commands.ownerAllowFrom` شامل `telegram:` است. ### یافتن شناسه کاربری Telegram روش امن‌تر (بدون ربات شخص ثالث): به ربات خود پیام خصوصی بدهید، `openclaw logs --follow` را اجرا کنید و `from.id` را بخوانید. روش رسمی Bot API: ```bash curl "https://api.telegram.org/bot/getUpdates" ``` شخص ثالث (با حریم خصوصی کمتر): `@userinfobot` یا `@getidsbot`. دو کنترل با هم اعمال می‌شوند: 1. **کدام گروه‌ها مجاز هستند** (`channels.telegram.groups`) - بدون پیکربندی `groups`، با `groupPolicy: "open"`: هر گروهی بررسی شناسه گروه را پشت سر می‌گذارد - بدون پیکربندی `groups`، با `groupPolicy: "allowlist"` (پیش‌فرض): همه گروه‌ها تا زمانی که ورودی‌های `groups` (یا `"*"`) را اضافه کنید مسدود هستند - `groups` پیکربندی‌شده: به‌عنوان فهرست مجاز عمل می‌کند (شناسه‌های صریح یا `"*"`) 2. **کدام فرستندگان در گروه‌ها مجاز هستند** (`channels.telegram.groupPolicy`) - `open` / `allowlist` (پیش‌فرض) / `disabled` `groupAllowFrom` فرستندگان گروه را فیلتر می‌کند؛ اگر تنظیم نشده باشد، Telegram به `allowFrom` برمی‌گردد (نه ذخیره‌گاه جفت‌سازی — مجوز فرستنده گروه هرگز تأییدهای ذخیره‌گاه جفت‌سازی پیام خصوصی را به ارث نمی‌برد؛ این از `2026.2.25` یک مرز امنیتی است). ورودی‌های `groupAllowFrom` باید شناسه‌های عددی کاربران Telegram باشند (پیشوندهای `telegram:` / `tg:` نرمال‌سازی می‌شوند)؛ ورودی‌های غیرعددی نادیده گرفته می‌شوند. شناسه گفت‌وگوی گروه یا ابرگروه را اینجا قرار ندهید — شناسه‌های منفی گفت‌وگو باید زیر `channels.telegram.groups` قرار گیرند. الگوی عملی برای ربات‌های تک‌مالک: شناسه کاربری خود را در `channels.telegram.allowFrom` تنظیم کنید، `groupAllowFrom` را تنظیم‌نشده باقی بگذارید و گروه‌های هدف را زیر `channels.telegram.groups` مجاز کنید. اگر `channels.telegram` به‌طور کامل در پیکربندی وجود نداشته باشد، زمان اجرا به‌طور پیش‌فرض از `groupPolicy="allowlist"` مسدودکننده استفاده می‌کند، مگر اینکه `channels.defaults.groupPolicy` به‌صراحت تنظیم شده باشد. راه‌اندازی گروه مختص مالک: ```json5 { channels: { telegram: { enabled: true, dmPolicy: "pairing", allowFrom: [""], groupPolicy: "allowlist", groups: { "": { requireMention: true, }, }, }, }, } ``` با `@ ping` از داخل گروه آزمایش کنید. تا زمانی که `requireMention: true`، پیام‌های عادی گروه ربات را فعال نمی‌کنند. اجازه دادن به همه اعضا در یک گروه مشخص: ```json5 { channels: { telegram: { groups: { "-1001234567890": { groupPolicy: "open", requireMention: false, }, }, }, }, } ``` اجازه دادن فقط به کاربران مشخص در یک گروه مشخص: ```json5 { channels: { telegram: { groups: { "-1001234567890": { requireMention: true, allowFrom: ["8734062810", "745123456"], }, }, }, }, } ``` اشتباه رایج: `groupAllowFrom` فهرست مجاز گروه نیست. - شناسه‌های منفی گفت‌وگوی گروه/ابرگروه Telegram (`-1001234567890`) باید زیر `channels.telegram.groups` قرار گیرند. - شناسه‌های کاربران Telegram (`8734062810`) باید زیر `groupAllowFrom` قرار گیرند تا تعیین شود کدام افراد درون یک گروه مجاز می‌توانند ربات را فعال کنند. - فقط برای اینکه همه اعضای یک گروه مجاز بتوانند با ربات صحبت کنند، از `groupAllowFrom: ["*"]` استفاده کنید. پاسخ‌های گروه به‌طور پیش‌فرض نیازمند اشاره هستند. اشاره می‌تواند از یکی از این روش‌ها باشد: - یک اشاره بومی `@botusername`، یا - یک الگوی اشاره در `agents.list[].groupChat.mentionPatterns` یا `messages.groupChat.mentionPatterns` گزینه‌های سطح نشست (فقط وضعیت، بدون ماندگاری): `/activation always`، `/activation mention`. برای ماندگاری از پیکربندی استفاده کنید: ```json5 { channels: { telegram: { groups: { "*": { requireMention: false }, }, }, }, } ``` بافت تاریخچه گروه همیشه فعال است و با `historyLimit` محدود می‌شود. برای غیرفعال کردن پنجره تاریخچه گروه، `channels.telegram.historyLimit: 0` را تنظیم کنید. `openclaw doctor --fix` کلید بازنشسته `includeGroupHistoryContext` را حذف می‌کند. دریافت شناسه گفت‌وگوی گروه: یک پیام گروه را به `@userinfobot` / `@getidsbot` هدایت کنید، `chat.id` را از `openclaw logs --follow` بخوانید، `getUpdates` در Bot API را بررسی کنید، یا (پس از مجاز شدن گروه) `/whoami@` را اجرا کنید. ## رفتار زمان اجرا - Telegram درون فرایند Gateway اجرا می‌شود. - مسیریابی قطعی است: پاسخ پیام ورودی Telegram به Telegram بازمی‌گردد (مدل کانال‌ها را انتخاب نمی‌کند). - پیام‌های ورودی به پاکت مشترک کانال، شامل فراداده پاسخ، جای‌نگهدارهای رسانه و زمینه ماندگار زنجیره پاسخ برای پاسخ‌هایی که Gateway مشاهده کرده است، نرمال‌سازی می‌شوند. - نشست‌های گروهی بر اساس شناسه گروه از هم جدا می‌شوند. موضوعات انجمن `:topic:` را اضافه می‌کنند. - پیام‌های خصوصی می‌توانند حامل `message_thread_id` باشند؛ OpenClaw آن را برای پاسخ‌ها حفظ می‌کند. نشست‌های موضوعی پیام خصوصی فقط زمانی تفکیک می‌شوند که Telegram `getMe` مقدار `has_topics_enabled: true` را برای ربات گزارش کند؛ در غیر این صورت، پیام‌های خصوصی در نشست تخت باقی می‌مانند. - نظرسنجی طولانی از اجراکننده grammY با ترتیب‌دهی به‌ازای هر گفت‌وگو/رشته استفاده می‌کند. هم‌زمانی مقصد اجراکننده از `agents.defaults.maxConcurrent` استفاده می‌کند. - راه‌اندازی چندحسابی، تعداد کاوش‌های هم‌زمان `getMe` را محدود می‌کند تا ناوگان‌های بزرگ ربات، کاوش همه حساب‌ها را یک‌باره پخش نکنند. - هر فرایند Gateway از نظرسنجی طولانی محافظت می‌کند تا در هر لحظه فقط یک نظرسنج فعال بتواند از توکن ربات استفاده کند. تعارض‌های پایدار 409 در `getUpdates` نشان می‌دهند Gateway دیگری از OpenClaw، یک اسکریپت یا نظرسنجی خارجی از همان توکن استفاده می‌کند. - نگهبان نظرسنجی به‌طور پیش‌فرض پس از 120 ثانیه بدون تکمیل زنده‌بودن `getUpdates`، راه‌اندازی مجدد می‌شود. مقدار `channels.telegram.pollingStallThresholdMs` را (30000-600000، با پشتیبانی از بازنویسی به‌ازای هر حساب) فقط زمانی افزایش دهید که استقرار شما هنگام کارهای طولانی‌مدت با راه‌اندازی مجدد کاذب ناشی از توقف نظرسنجی مواجه می‌شود. - Telegram Bot API از رسید خواندن پشتیبانی نمی‌کند (`sendReadReceipts` اعمال نمی‌شود). `channels.telegram.dm.threadReplies` و `channels.telegram.direct..threadReplies` حذف شده‌اند. اگر پیکربندی شما پس از ارتقا همچنان این کلیدها را دارد، `openclaw doctor --fix` را اجرا کنید. اکنون مسیریابی موضوع پیام خصوصی از `getMe.has_topics_enabled` در Telegram پیروی می‌کند (که با حالت رشته‌ای BotFather کنترل می‌شود): ربات‌هایی که موضوعات در آن‌ها فعال است، وقتی Telegram مقدار `message_thread_id` را می‌فرستد، از نشست‌های پیام خصوصی با دامنه رشته استفاده می‌کنند؛ سایر پیام‌های خصوصی در نشست تخت باقی می‌مانند. ## مرجع قابلیت‌ها 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`+). ویرایش‌های پیش‌نمایش پاسخ را حفظ کنید، اما سطرهای پیشرفت ابزار را پنهان کنید: ```json { "channels": { "telegram": { "streaming": { "mode": "partial", "preview": { "toolProgress": false } } } } } ``` پیشرفت ابزار را نمایان نگه دارید، اما متن فرمان/اجرا را پنهان کنید: ```json { "channels": { "telegram": { "streaming": { "mode": "partial", "preview": { "commandText": "status" } } } } } ``` حالت `progress` پیشرفت ابزار را بدون ویرایش پاسخ نهایی درون آن پیام نشان می‌دهد. سیاست متن فرمان را زیر `streaming.progress` قرار دهید: ```json { "channels": { "telegram": { "streaming": { "mode": "progress", "progress": { "toolProgress": true, "commandText": "status" } } } } } ``` `streaming.mode: "off"` ویرایش‌های پیش‌نمایش را غیرفعال می‌کند و به‌جای فرستادن گفت‌وگوی عمومی ابزار/پیشرفت به‌صورت پیام‌های وضعیت مستقل، آن را سرکوب می‌کند؛ درخواست‌های تأیید، رسانه و خطاها همچنان از مسیر تحویل نهایی عادی عبور می‌کنند. `streaming.preview.toolProgress: false` فقط ویرایش‌های پیش‌نمایش پاسخ را نگه می‌دارد. پاسخ به نقل‌قول انتخاب‌شده استثنا است. وقتی `replyToMode` برابر `first`، `all` یا `batched` باشد و پیام ورودی متن نقل‌قول انتخاب‌شده داشته باشد، OpenClaw به‌جای ویرایش پیش‌نمایش پاسخ، پاسخ نهایی را از مسیر بومی پاسخ به نقل‌قول Telegram می‌فرستد؛ بنابراین `streaming.preview.toolProgress` نمی‌تواند در آن نوبت سطرهای وضعیت را نشان دهد. پاسخ به پیام جاری بدون متن نقل‌قول انتخاب‌شده همچنان پخش می‌شود. وقتی نمایان‌بودن پیشرفت ابزار از پاسخ بومی به نقل‌قول مهم‌تر است، `replyToMode: "off"` را تنظیم کنید؛ یا برای پذیرفتن این مصالحه، `streaming.preview.toolProgress: false` را تنظیم کنید. برای پاسخ‌های فقط‌متنی: پیش‌نمایش‌های کوتاه با ویرایش نهایی در همان محل تکمیل می‌شوند؛ پاسخ‌های نهایی طولانی که به چند پیام تقسیم می‌شوند، از پیش‌نمایش به‌عنوان بخش اول دوباره استفاده می‌کنند و سپس فقط باقی‌مانده را می‌فرستند؛ پاسخ‌های نهایی حالت پیشرفت، پیش‌نویس وضعیت را پاک می‌کنند و از تحویل نهایی عادی استفاده می‌کنند؛ اگر ویرایش نهایی پیش از تأیید تکمیل شکست بخورد، OpenClaw به تحویل نهایی عادی بازمی‌گردد و پیش‌نمایش منسوخ را پاک می‌کند. برای پاسخ‌های پیچیده (محموله‌های رسانه‌ای)، OpenClaw همیشه به تحویل نهایی عادی بازمی‌گردد و پیش‌نمایش را پاک می‌کند. پخش پیش‌نمایش و پخش بلوکی با یکدیگر ناسازگارند — وقتی پخش بلوکی صراحتاً فعال باشد، OpenClaw برای جلوگیری از پخش دوگانه، پخش پیش‌نمایش را نادیده می‌گیرد. استدلال: `/reasoning stream` هنگام تولید، استدلال را در پیش‌نمایش زنده پخش می‌کند و سپس پیش‌نمایش استدلال را پس از تحویل نهایی حذف می‌کند (برای نمایان نگه‌داشتن آن از `/reasoning on` استفاده کنید). پاسخ نهایی بدون متن استدلال فرستاده می‌شود. متن خروجی به‌طور پیش‌فرض از پیام‌های استاندارد HTML در Telegram استفاده می‌کند که در سرویس‌گیرنده‌های فعلی خوانا هستند: ضخیم، مورب، پیوندها، کد، متن‌های پوشیده و نقل‌قول‌ها — نه بلوک‌های صرفاً غنی Bot API 10.2 (جدول‌های بومی، جزئیات، رسانه غنی و فرمول‌ها). برای استفاده از پیام‌های غنی Bot API 10.2: ```json5 { 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 فعال می‌کند. ورودی‌های سفارشی به منوی فرمان اضافه کنید: ```json5 { channels: { telegram: { customCommands: [ { command: "backup", description: "پشتیبان‌گیری Git" }, { command: "generate", description: "ایجاد یک تصویر" }, ], }, }, } ``` قواعد: نام‌ها نرمال‌سازی می‌شوند (`/` ابتدایی حذف می‌شود و حروف کوچک می‌شوند)؛ الگوی معتبر `a-z`، `0-9`، `_`، با طول 1-32؛ فرمان‌های سفارشی نمی‌توانند فرمان‌های بومی را بازنویسی کنند؛ تعارض‌ها/موارد تکراری نادیده گرفته و ثبت می‌شوند. فرمان‌های سفارشی فقط ورودی‌های منو هستند — رفتار را به‌طور خودکار پیاده‌سازی نمی‌کنند. فرمان‌های Plugin/مهارت همچنان می‌توانند هنگام تایپ‌شدن کار کنند، حتی اگر در منوی Telegram نمایش داده نشوند. اگر فرمان‌های بومی غیرفعال باشند، فرمان‌های داخلی حذف می‌شوند؛ فرمان‌های سفارشی/Plugin در صورت پیکربندی همچنان ممکن است ثبت شوند. خطاهای رایج راه‌اندازی: - `setMyCommands failed` همراه با `BOT_COMMANDS_TOO_MUCH` پس از تلاش مجدد برای کوتاه‌سازی به این معنا است که منو همچنان از ظرفیت فراتر می‌رود؛ تعداد فرمان‌های Plugin/مهارت/سفارشی را کاهش دهید یا `channels.telegram.commands.native` را غیرفعال کنید. - شکست `deleteWebhook`، `deleteMyCommands` یا `setMyCommands` با `404: Not Found`، درحالی‌که فرمان‌های مستقیم curl برای Bot API کار می‌کنند، معمولاً به این معنا است که `channels.telegram.apiRoot` روی نشانی کامل `/bot` تنظیم شده است. `apiRoot` باید فقط ریشه Bot API باشد؛ `openclaw doctor --fix` یک `/bot` انتهایی ناخواسته را حذف می‌کند. - `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 `، `/pair approve` (تنها درخواست در انتظار) یا `/pair approve latest` اگر دستگاهی با جزئیات احراز هویت تغییریافته (نقش، دامنه‌ها، کلید عمومی) دوباره تلاش کند، درخواست در انتظار قبلی با یک `requestId` جدید جایگزین می‌شود؛ پیش از تأیید، `/pair pending` را دوباره اجرا کنید. جزئیات بیشتر: [جفت‌سازی](/fa/channels/pairing#pair-via-telegram). دامنه صفحه‌کلید درون‌خطی را پیکربندی کنید: ```json5 { channels: { telegram: { capabilities: { inlineButtons: "allowlist", }, }, }, } ``` بازنویسی به‌ازای هر حساب: ```json5 { channels: { telegram: { accounts: { main: { capabilities: { inlineButtons: "allowlist", }, }, }, }, }, } ``` دامنه‌ها: `off`، `dm`، `group`، `all`، `allowlist` (پیش‌فرض). مقدار قدیمی `capabilities: ["inlineButtons"]` به `"all"` نگاشت می‌شود. نمونه کنش پیام: ```json5 { action: "send", channel: "telegram", to: "123456789", message: "یک گزینه انتخاب کنید:", buttons: [ [ { text: "بله", callback_data: "yes" }, { text: "خیر", callback_data: "no" }, ], [{ text: "لغو", callback_data: "cancel" }], ], } ``` نمونه دکمه Mini App: ```json5 { action: "send", channel: "telegram", to: "123456789", message: "باز کردن برنامه:", presentation: { blocks: [ { type: "buttons", buttons: [{ label: "راه‌اندازی", web_app: { url: "https://example.com/app" } }], }, ], }, } ``` دکمه‌های `web_app` فقط در گفت‌وگوهای خصوصی میان کاربر و ربات کار می‌کنند. کلیک‌های callback که توسط یک کنترل‌کننده تعاملی ثبت‌شده در Plugin دریافت نمی‌شوند، به‌صورت متن به عامل فرستاده می‌شوند: `callback_data: `. کنش‌ها: - `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](/fa/tools/reactions). برچسب‌های صریح رشته‌بندی پاسخ در خروجی تولیدشده: - `[[reply_to_current]]` — به پیام آغازگر پاسخ می‌دهد - `[[reply_to:]]` — به شناسه پیام مشخصی پاسخ می‌دهد `channels.telegram.replyToMode`: `off` (پیش‌فرض)، `first`، `all`. وقتی رشته‌بندی پاسخ فعال باشد و متن/عنوان اصلی در دسترس باشد، OpenClaw به‌طور خودکار یک گزیده نقل‌قول بومی اضافه می‌کند. Telegram متن نقل‌قول بومی را به 1024 واحد کد UTF-16 محدود می‌کند؛ پیام‌های طولانی‌تر از ابتدا نقل می‌شوند و اگر Telegram نقل‌قول را رد کند، به پاسخ ساده بازمی‌گردند. `off` فقط رشته‌بندی ضمنی پاسخ را غیرفعال می‌کند؛ برچسب‌های صریح `[[reply_to_*]]` همچنان رعایت می‌شوند. ابرگروه‌های انجمن: کلیدهای نشست موضوع، `:topic:` را اضافه می‌کنند؛ پاسخ‌ها و نشانگر تایپ، رشته موضوع را هدف می‌گیرند؛ مسیر پیکربندی موضوع `channels.telegram.groups..topics.` است. موضوع عمومی (`threadId=1`) یک حالت ویژه است: ارسال پیام `message_thread_id` را حذف می‌کند (Telegram مقدار `sendMessage(...thread_id=1)` را با پیام «رشته یافت نشد» رد می‌کند)، اما کنش‌های تایپ همچنان `message_thread_id` را شامل می‌شوند (طبق تجربه برای نمایش نشانگر تایپ ضروری است). ورودی‌های موضوع، تنظیمات گروه را به ارث می‌برند، مگر اینکه بازنویسی شوند (`requireMention`، `allowFrom`، `skills`، `systemPrompt`، `enabled`، `groupPolicy`). `agentId` فقط مخصوص موضوع است و از پیش‌فرض‌های گروه ارث نمی‌برد. `topics."*"` پیش‌فرض‌های تمام موضوعات آن گروه را تعیین می‌کند؛ شناسه‌های دقیق موضوع همچنان بر `"*"` اولویت دارند. **مسیریابی عامل به‌ازای هر موضوع**: هر موضوع می‌تواند از طریق `agentId` در پیکربندی موضوع به عامل متفاوتی هدایت شود و فضای کاری، حافظه و نشست مختص خود را داشته باشد: ```json5 { 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](/fa/tools/acp-agents) را ببینید. **ایجاد ACP متصل به رشته از چت**: `/acp spawn --thread here|auto` موضوع فعلی را به یک نشست جدید ACP متصل می‌کند؛ پیام‌های بعدی مستقیماً به آن هدایت می‌شوند و OpenClaw تأیید ایجاد را در همان موضوع سنجاق می‌کند. به `channels.telegram.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]]` را در پاسخ عامل قرار دهید. رونویسی یادداشت‌های صوتی ورودی در زمینه عامل به‌صورت متن تولیدشده توسط ماشین و غیرقابل‌اعتماد ارائه می‌شود، اما تشخیص اشاره همچنان از رونویسی خام استفاده می‌کند تا پیام‌های صوتی وابسته به اشاره همچنان کار کنند. ```json5 { action: "send", channel: "telegram", to: "123456789", media: "https://example.com/voice.ogg", asVoice: true, } ``` ### پیام‌های ویدئویی Telegram فایل‌های ویدئویی را از یادداشت‌های ویدئویی متمایز می‌کند. یادداشت‌های ویدئویی از عنوان پشتیبانی نمی‌کنند؛ متن پیام ارائه‌شده جداگانه ارسال می‌شود. ```json5 { action: "send", channel: "telegram", to: "123456789", media: "https://example.com/video.mp4", asVideoNote: true, } ``` ### مکان‌ها و محل‌ها از کنش موجود `send` با یک شیء مستقل `location` استفاده کنید. مختصات یک سنجاق بومی ارسال می‌کنند؛ افزودن هر دو `name` و `address` یک کارت مکان بومی ارسال می‌کند. ارسال مکان را نمی‌توان با متن پیام یا رسانه ترکیب کرد. ```json5 { action: "send", channel: "telegram", to: "123456789", location: { latitude: 48.858844, longitude: 2.294351, accuracy: 12, name: "برج ایفل", address: "شان دو مارس، پاریس", }, } ``` ### استیکرها ورودی: WEBP ایستا دانلود و پردازش می‌شود (جای‌نگهدار ``)؛ TGS متحرک و WEBM ویدئویی نادیده گرفته می‌شوند. فیلدهای زمینه استیکر: `Sticker.emoji`، `Sticker.setName`، `Sticker.fileId`، `Sticker.fileUniqueId`، `Sticker.cachedDescription`. توضیحات در وضعیت Plugin در SQLite مربوط به OpenClaw ذخیره موقت می‌شوند تا فراخوانی‌های تکراری بینایی کاهش یابد. فعال‌سازی کنش‌های استیکر: ```json5 { channels: { telegram: { actions: { sticker: true, }, }, }, } ``` ارسال: ```json5 { action: "sticker", channel: "telegram", to: "123456789", fileId: "CAACAgIAAxkBAAI...", } ``` جست‌وجوی استیکرهای ذخیره‌شده: ```json5 { 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..ackReaction` - `channels.telegram.ackReaction` - `messages.ackReaction` - ایموجی جایگزین هویت عامل (`agents.list[].identity.emoji`، در غیر این صورت "👀") Telegram انتظار یک ایموجی یونیکد را دارد (برای مثال "👀")؛ برای غیرفعال‌کردن واکنش در یک کانال یا حساب، از `""` استفاده کنید. **دامنه (`messages.ackReactionScope`، پیش‌فرض `"group-mentions"`؛ در حال حاضر بازنویسی در سطح حساب یا کانال Telegram وجود ندارد):** `all` (پیام‌های مستقیم + گروه‌ها، شامل رویدادهای محیطی اتاق)، `direct` (فقط پیام‌های مستقیم)، `group-all` (تمام پیام‌های گروه به‌جز رویدادهای محیطی اتاق، بدون پیام مستقیم)، `group-mentions` (گروه‌ها هنگامی که به ربات اشاره شود؛ **بدون پیام مستقیم** — پیش‌فرض)، `off` / `none` (غیرفعال). دامنه پیش‌فرض (`group-mentions`) واکنش تأیید دریافت را در پیام‌های مستقیم یا رویدادهای محیطی اتاق فعال نمی‌کند. برای پیام‌های مستقیم از `direct` یا `all` استفاده کنید؛ فقط `all` رویدادهای محیطی اتاق را تأیید می‌کند. این مقدار هنگام راه‌اندازی ارائه‌دهنده Telegram خوانده می‌شود؛ بنابراین برای اعمال تغییر باید Gateway را دوباره راه‌اندازی کرد. نوشتن پیکربندی کانال به‌طور پیش‌فرض فعال است (`configWrites !== false`). نوشتن‌هایی که Telegram آغاز می‌کند شامل رویدادهای انتقال گروه (`migrate_to_chat_id`، به‌روزرسانی `channels.telegram.groups`) و `/config set` / `/config unset` است (نیازمند فعال‌بودن فرمان). غیرفعال‌سازی: ```json5 { channels: { telegram: { configWrites: false, }, }, } ``` پیش‌فرض polling طولانی است. برای حالت webhook، `channels.telegram.webhookUrl` و `channels.telegram.webhookSecret` را تنظیم کنید؛ `webhookPath` اختیاری (پیش‌فرض `/telegram-webhook`)، `webhookHost` (پیش‌فرض `127.0.0.1`)، `webhookPort` (پیش‌فرض `8787`) و `webhookCertPath` (گواهی PEM خودامضا برای راه‌اندازی با IP مستقیم یا بدون دامنه). در حالت polling طولانی، OpenClaw نشان‌گذاری راه‌اندازی مجدد خود را فقط پس از توزیع موفق یک به‌روزرسانی پایدار می‌کند؛ اگر کنترل‌کننده شکست بخورد، آن به‌روزرسانی در همان فرایند قابل تلاش مجدد باقی می‌ماند و تکمیل‌شده علامت‌گذاری نمی‌شود. شنونده محلی به‌طور پیش‌فرض به `127.0.0.1:8787` متصل می‌شود. برای ورودی عمومی، یک پراکسی معکوس جلوی درگاه محلی قرار دهید یا `webhookHost: "0.0.0.0"` را آگاهانه تنظیم کنید. حالت Webhook محافظ‌های درخواست، توکن محرمانه Telegram و بدنه JSON را اعتبارسنجی می‌کند، سپس پیش از بازگرداندن یک `200` خالی، به‌روزرسانی را در صف ورودی پایدار ثبت می‌کند. پذیرش پایدار موفق شامل `x-openclaw-delivery-accepted: durable` است؛ پاسخ‌های مربوط به سلامت، مسیریابی، احراز هویت، اعتبارسنجی و خطاهای ذخیره‌سازی این سرآیند را حذف می‌کنند. پراکسی‌های معکوس و کنترل‌کننده‌های میزبان می‌توانند این سرآیند را الزامی کنند تا پذیرش OpenClaw را از یک `200` خالی عمومی تشخیص دهند، بدون اینکه پذیرش را از زمان‌بندی پاسخ استنباط کنند. سپس OpenClaw به‌روزرسانی را به‌صورت ناهمگام و از طریق همان مسیرهای ربات به‌ازای هر چت/موضوع که در polling طولانی استفاده می‌شوند پردازش می‌کند؛ بنابراین نوبت‌های کند عامل، ACK تحویل Telegram را معطل نمی‌کنند. - `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، تحویل پاسخ قابل‌مشاهده را متوقف نکند. نظرسنجی طولانی همچنان از محافظ درخواست 45 ثانیه‌ای `getUpdates` استفاده می‌کند تا نظرسنجی‌های بی‌کار برای همیشه رها نشوند. - `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[""].historyLimit`. - `channels.telegram.retry` برای خطاهای قابل‌بازیابی API خروجی، بر کمک‌کننده‌های ارسال Telegram ‏(CLI/ابزارها/کنش‌ها) اعمال می‌شود. تحویل پاسخ نهایی ورودی برای شکست‌های پیش از اتصال از تلاش مجدد محدودِ ارسال ایمن استفاده می‌کند، اما پوشش‌های شبکه مبهم پس از ارسال را که ممکن است پیام‌های قابل‌مشاهده را تکراری کنند، دوباره امتحان نمی‌کند. مقصدهای ارسال در CLI و ابزار پیام، شناسه عددی گفت‌وگو، نام کاربری یا مقصد موضوع انجمن را می‌پذیرند: ```bash 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` استفاده می‌کنند و از موضوعات انجمن پشتیبانی می‌کنند: ```bash 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 تفکیک می‌شوند؛ سایر شناسه‌ها ابتدا از طریق تأییدهای اجرای دستور تفکیک می‌شوند. [تأییدهای اجرای دستور](/fa/tools/exec-approvals) را ببینید. ## کنترل پاسخ‌های خطا هنگامی که عامل با خطای تحویل یا ارائه‌دهنده مواجه می‌شود، سیاست خطا تعیین می‌کند که آیا پیام‌های خطا به گفت‌وگوی Telegram برسند یا خیر: | کلید | مقادیر | پیش‌فرض | توضیحات | | ----------------------------------- | -------------------------- | --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `channels.telegram.errorPolicy` | `always`، `once`، `silent` | `always` | `always` همه پیام‌های خطا را به گفت‌وگو ارسال می‌کند. `once` هر پیام خطای یکتا را در هر بازه انتظار یک‌بار ارسال می‌کند (خطاهای یکسان تکراری را سرکوب می‌کند). `silent` هرگز پیام خطا را به گفت‌وگو ارسال نمی‌کند. | | `channels.telegram.errorCooldownMs` | عدد (ms) | `14400000` (4h) | بازه انتظار برای سیاست `once`. پس از ارسال یک خطا، همان پیام تا سپری شدن این بازه سرکوب می‌شود. از انباشت پیام‌های خطا هنگام قطعی جلوگیری می‌کند. | بازنویسی در سطح حساب، گروه و موضوع پشتیبانی می‌شود (با همان وراثت سایر کلیدهای پیکربندی Telegram). ```json5 { channels: { telegram: { errorPolicy: "always", errorCooldownMs: 120000, groups: { "-1001234567890": { errorPolicy: "silent", // خطاها را در این گروه سرکوب می‌کند }, }, }, }, } ``` ## عیب‌یابی - اگر `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 دوباره امتحان می‌شوند. خطاهای پایدار شبکه/fetch معمولاً به این معنا هستند که DNS/HTTPS برای `api.telegram.org` در دسترس نیست. - `getMe returned 401` یک شکست احراز هویت Telegram برای توکن پیکربندی‌شده ربات است. توکن را در BotFather دوباره کپی یا تولید کنید، سپس `channels.telegram.botToken`، `tokenFile`، `accounts..botToken` یا `TELEGRAM_BOT_TOKEN` (حساب پیش‌فرض) را به‌روزرسانی کنید. - `deleteWebhook 401 Unauthorized` هنگام راه‌اندازی نیز یک شکست احراز هویت است؛ تلقی آن به‌عنوان «هیچ Webhookای وجود ندارد» فقط همان شکست ناشی از توکن نامعتبر را تا یک فراخوانی بعدی API به تعویق می‌اندازد. - Node 22+ همراه با fetch/پراکسی سفارشی، در صورت ناسازگاری نوع‌های `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 را دوباره امتحان می‌کند. - اگر سوکت‌های 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 ناپایدار، فراخوانی‌های API ‏Telegram را از طریق یک پراکسی مسیریابی کنید: ```yaml channels: telegram: proxy: socks5://:@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 بهتر کار می‌کند، انتخاب خانواده را اجباری کنید: ```yaml channels: telegram: network: autoSelectFamily: false ``` - پاسخ‌های محدوده معیار RFC 2544 ‏(`198.18.0.0/15`) از قبل به‌طور پیش‌فرض برای بارگیری رسانه‌های Telegram مجاز هستند. اگر هنگام بارگیری رسانه، یک پراکسی fake-IP یا شفافِ مورداعتماد، `api.telegram.org` را به نشانی خصوصی/داخلی/با کاربرد ویژه دیگری بازنویسی می‌کند، میان‌بُر مختص Telegram را فعال کنید: ```yaml channels: telegram: network: dangerouslyAllowPrivateNetwork: true ``` - همین قابلیت فعال‌سازی برای هر حساب در `channels.telegram.accounts..network.dangerouslyAllowPrivateNetwork` نیز موجود است. - اگر پراکسی شما میزبان‌های رسانه Telegram را به `198.18.x.x` تفکیک می‌کند، ابتدا پرچم خطرناک را خاموش نگه دارید — این محدوده از قبل به‌طور پیش‌فرض مجاز است. `channels.telegram.network.dangerouslyAllowPrivateNetwork` محافظت‌های SSRF رسانه Telegram را تضعیف می‌کند. فقط در محیط‌های پراکسی مورداعتماد و تحت‌کنترل اپراتور (مسیریابی fake-IP در Clash، Mihomo و Surge) که پاسخ‌های خصوصی یا با کاربرد ویژه خارج از محدوده معیار RFC 2544 تولید می‌کنند، از آن استفاده کنید. برای دسترسی عادی Telegram از طریق اینترنت عمومی، آن را خاموش نگه دارید. - بازنویسی‌های موقت محیطی: `OPENCLAW_TELEGRAM_DISABLE_AUTO_SELECT_FAMILY=1`، `OPENCLAW_TELEGRAM_ENABLE_AUTO_SELECT_FAMILY=1`، `OPENCLAW_TELEGRAM_DNS_RESULT_ORDER=ipv4first`. - پاسخ‌های DNS را اعتبارسنجی کنید: ```bash dig +short api.telegram.org A dig +short api.telegram.org AAAA ``` راهنمای بیشتر: [عیب‌یابی کانال](/fa/channels/troubleshooting). ## مرجع پیکربندی مرجع اصلی: [مرجع پیکربندی - Telegram](/fa/gateway/config-channels#telegram). - راه‌اندازی/احراز هویت: `enabled`، `botToken`، `tokenFile` (باید یک فایل معمولی باشد؛ پیوندهای نمادین رد می‌شوند)، `accounts.*` - کنترل دسترسی: `dmPolicy`، `allowFrom`، `groupPolicy`، `groupAllowFrom`، `groups`، `groups.*.topics.*`، `bindings[]` در سطح بالا (`type: "acp"`) - پیش‌فرض‌های موضوع: `groups..topics."*"` برای موضوعات انجمنیِ تطبیق‌نیافته اعمال می‌شود؛ شناسه‌های دقیق موضوع آن را بازنویسی می‌کنند - تأییدهای اجرا: `execApprovals`، `accounts.*.execApprovals` - فرمان/منو: `commands.native`، `commands.nativeSkills`، `customCommands` - رشته‌بندی/پاسخ‌ها: `replyToMode`، `threadBindings` - پخش جریانی: `streaming` (حالت‌های `off | partial | block | progress`)، `streaming.preview.toolProgress` - قالب‌بندی/تحویل: `textChunkLimit`، `streaming.chunkMode`، `richMessages`، `markdown.tables` ‏(`off | bullets | code | block`)، `linkPreview`، `responsePrefix` - رسانه/شبکه: `mediaMaxMb`، `mediaGroupFlushMs`، `timeoutSeconds`، `pollingStallThresholdMs`، `retry`، `network.autoSelectFamily`، `network.dangerouslyAllowPrivateNetwork`، `proxy` - ریشه API سفارشی: `apiRoot` (فقط ریشه Bot API؛ `/bot` را درج نکنید)، `trustedLocalFileRoots` (ریشه‌های مطلق `file_path` برای Bot API خودمیزبان) - Webhook: `webhookUrl`، `webhookSecret`، `webhookPath`، `webhookHost`، `webhookPort`، `webhookCertPath` - کنش‌ها/قابلیت‌ها: `capabilities.inlineButtons`، `actions.sendMessage|editMessage|deleteMessage|reactions|sticker|createForumTopic|editForumTopic` - واکنش‌ها: `reactionNotifications`، `reactionLevel` - خطاها: `errorPolicy`، `errorCooldownMs`، `silentErrorReplies` - نوشتن/تاریخچه: `configWrites`، `historyLimit`، `dmHistoryLimit`، `dms.*.historyLimit` تقدم چندحسابی: هنگامی که دو یا چند شناسه حساب پیکربندی شده‌اند، برای صریح‌کردن مسیریابی پیش‌فرض، `channels.telegram.defaultAccount` را تنظیم کنید (یا `channels.telegram.accounts.default` را بگنجانید). در غیر این صورت، OpenClaw به نخستین شناسه حساب نرمال‌شده بازمی‌گردد و `openclaw doctor` هشدار می‌دهد. حساب‌های نام‌گذاری‌شده، `channels.telegram.allowFrom` / `groupAllowFrom` را به ارث می‌برند، اما مقادیر `accounts.default.*` را به ارث نمی‌برند. ## مرتبط یک کاربر Telegram را با Gateway جفت کنید. رفتار فهرست مجاز گروه و موضوع. پیام‌های ورودی را به عامل‌ها مسیریابی کنید. مدل تهدید و مقاوم‌سازی. گروه‌ها و موضوعات را به عامل‌ها نگاشت کنید. عیب‌یابی میان‌کانالی.