Telegram

Telegram botları varsayılan olarak aldıkları grup mesajlarını sınırlayan Gizlilik Modu ile gelir.

Botun tüm grup mesajlarını görmesi gerekiyorsa şunlardan birini yapın:

• /setprivacy ile gizlilik modunu devre dışı bırakın veya
• botu grup yöneticisi yapın.

Gizlilik modunu değiştirirken Telegram'ın değişikliği uygulaması için botu her gruptan kaldırıp yeniden ekleyin.

Yönetici durumu Telegram grup ayarlarında denetlenir.

Yönetici botlar tüm grup mesajlarını alır; bu, her zaman açık grup davranışı için kullanışlıdır.

• grup eklemelerine izin vermek/reddetmek için /setjoingroups
• grup görünürlüğü davranışı için /setprivacy

OpenClaw kısmi yanıtları gerçek zamanlı olarak akıtabilir:

• doğrudan sohbetler: önizleme iletisi + editMessageText
• gruplar/konular: önizleme iletisi + editMessageText

Gereksinim:

• channels.telegram.streaming, off | partial | block | progress olur (varsayılan: partial)
• kısa ilk yanıt önizlemeleri debounce edilir, ardından çalıştırma hala etkinse sınırlı bir gecikmeden sonra somutlaştırılır
• progress, araç ilerlemesi için düzenlenebilir tek bir durum taslağını tutar, araç ilerlemesinden önce yanıt etkinliği geldiğinde kararlı durum etiketini gösterir, tamamlandığında temizler ve son yanıtı normal ileti olarak gönderir
• streaming.preview.toolProgress, araç/ilerleme güncellemelerinin aynı düzenlenen önizleme iletisini yeniden kullanıp kullanmayacağını denetler (varsayılan: önizleme akışı etkinken true)
• streaming.preview.commandText, bu araç ilerleme satırlarının içindeki komut/exec ayrıntısını denetler: raw (varsayılan, yayımlanmış davranışı korur) veya status (yalnızca araç etiketi)
• streaming.progress.commentary (varsayılan: false), geçici ilerleme taslağında assistant yorum/preamble metnini etkinleştirir
• eski channels.telegram.streamMode, boolean streaming değerleri ve emekli edilmiş yerel taslak önizleme anahtarları algılanır; bunları güncel akış yapılandırmasına taşımak için openclaw doctor --fix çalıştırın

Araç ilerleme önizleme güncellemeleri, araçlar çalışırken gösterilen kısa durum satırlarıdır; örneğin komut yürütme, dosya okumaları, planlama güncellemeleri, patch özetleri veya Codex app-server modunda Codex preamble/yorum metni. Telegram, v2026.4.22 ve sonrası yayımlanmış OpenClaw davranışıyla eşleşmesi için bunları varsayılan olarak etkin tutar.

Yanıt metni için düzenlenen önizlemeyi koruyup araç ilerleme satırlarını gizlemek için şunu ayarlayın:

{  "channels": {    "telegram": {      "streaming": {        "mode": "partial",        "preview": {          "toolProgress": false        }      }    }  }}

Araç ilerlemesini görünür tutup komut/exec metnini gizlemek için şunu ayarlayın:

{  "channels": {    "telegram": {      "streaming": {        "mode": "partial",        "preview": {          "commandText": "status"        }      }    }  }}

Son yanıtı aynı iletiye düzenlemeden görünür araç ilerlemesi istediğinizde progress modunu kullanın. Komut metni politikasını streaming.progress altına koyun:

{  "channels": {    "telegram": {      "streaming": {        "mode": "progress",        "progress": {          "toolProgress": true,          "commandText": "status"        }      }    }  }}

streaming.mode: "off" seçeneğini yalnızca yalnızca-son teslimat istediğinizde kullanın: Telegram önizleme düzenlemeleri devre dışı bırakılır ve genel araç/ilerleme sohbeti bağımsız durum iletileri olarak gönderilmek yerine bastırılır. Onay istemleri, medya yükleri ve hatalar normal son teslimat üzerinden yönlendirilmeye devam eder. Yalnızca araç ilerleme durum satırlarını gizlerken yanıt önizleme düzenlemelerini korumak istediğinizde streaming.preview.toolProgress: false kullanın.

Yalnızca metin yanıtları için:

• kısa DM/grup/konu önizlemeleri: OpenClaw aynı önizleme iletisini korur ve son düzenlemeyi yerinde yapar
• birden fazla Telegram iletisine bölünen uzun son metinler, mümkün olduğunda mevcut önizlemeyi ilk son parça olarak yeniden kullanır, sonra yalnızca kalan parçaları gönderir
• ilerleme modu son yanıtları durum taslağını temizler ve taslağı yanıta düzenlemek yerine normal son teslimatı kullanır
• tamamlanan metin onaylanmadan önce son düzenleme başarısız olursa OpenClaw normal son teslimatı kullanır ve eski önizlemeyi temizler

Karmaşık yanıtlar için (örneğin medya yükleri), OpenClaw normal son teslimata geri döner ve ardından önizleme iletisini temizler.

Önizleme akışı, blok akışından ayrıdır. Blok akışı Telegram için açıkça etkinleştirildiğinde OpenClaw çift akışı önlemek için önizleme akışını atlar.

Akıl yürütme akışı davranışı:

• /reasoning stream, desteklenen bir kanalın akıl yürütme önizleme yolunu kullanır; Telegram'da üretim sırasında akıl yürütmeyi canlı önizlemeye akıtır
• akıl yürütme önizlemesi son teslimattan sonra silinir; akıl yürütmenin görünür kalması gerektiğinde /reasoning on kullanın
• son yanıt akıl yürütme metni olmadan gönderilir

Giden metin, yanıtların güncel Telegram istemcilerinde okunabilir kalması için varsayılan olarak standart Telegram HTML iletileri kullanır. Bu uyumluluk modu normal kalın, italik, bağlantı, kod, spoiler ve alıntıları destekler; ancak yerel tablolar, ayrıntılar, zengin medya ve formüller gibi Bot API 10.1'e özgü zengin blokları desteklemez.

Bot API 10.1 zengin iletilerini etkinleştirmek için channels.telegram.richMessages: true ayarlayın:

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

Etkinleştirildiğinde:

• Aracıya, bu bot/hesap için Telegram zengin iletilerinin kullanılabilir olduğu söylenir.
• Markdown metni OpenClaw'ın Markdown IR'ı üzerinden işlenir ve Telegram zengin HTML olarak gönderilir.
• Açık zengin HTML yükleri başlıklar, tablolar, ayrıntılar, zengin medya ve formüller gibi desteklenen Bot API 10.1 etiketlerini korur.
• Medya açıklamaları yine Telegram HTML açıklamaları kullanır, çünkü zengin iletiler açıklamaların yerini almaz.

Bu, model metnini Telegram Rich Markdown işaretlerinden uzak tutar; böylece $400-600K gibi para birimleri matematik olarak ayrıştırılmaz. Uzun zengin metin, Telegram'ın zengin metin ve zengin blok sınırları boyunca otomatik olarak bölünür. Telegram'ın sütun sınırını aşan tablolar kod blokları olarak gönderilir.

Varsayılan: istemci uyumluluğu için kapalı. Zengin iletiler uyumlu Telegram istemcileri gerektirir; bazı güncel Desktop, Web, Android ve üçüncü taraf istemciler kabul edilen zengin iletileri desteklenmiyor olarak gösterir. Botla kullanılan her istemci bunları işleyemediği sürece bu seçeneği devre dışı bırakın. /status, geçerli Telegram oturumunda zengin iletilerin açık mı kapalı mı olduğunu gösterir.

Bağlantı önizlemeleri varsayılan olarak etkindir. channels.telegram.linkPreview: false, zengin metin için otomatik varlık algılamasını atlar.

Telegram komut menüsü kaydı başlangıçta setMyCommands ile ele alınır.

Yerel komut varsayılanları:

• commands.native: "auto", Telegram için yerel komutları etkinleştirir

Özel komut menüsü girişleri ekleyin:

{channels: {telegram: {  customCommands: [    { command: "backup", description: "Git backup" },    { command: "generate", description: "Create an image" },  ],},},}

Kurallar:

• adlar normalize edilir (baştaki / kaldırılır, küçük harfe çevrilir)
• geçerli desen: a-z, 0-9, _, uzunluk 1..32
• özel komutlar yerel komutları geçersiz kılamaz
• çakışmalar/yinelenenler atlanır ve günlüğe yazılır

Notlar:

• özel komutlar yalnızca menü girişleridir; davranışı otomatik olarak uygulamazlar
• plugin/skill komutları, Telegram menüsünde gösterilmese bile yazıldığında çalışabilir

Yerel komutlar devre dışıysa yerleşikler kaldırılır. Özel/plugin komutları yapılandırıldıysa yine de kaydolabilir.

Yaygın kurulum hataları:

• BOT_COMMANDS_TOO_MUCH ile setMyCommands failed, Telegram menüsünün kırpmadan sonra hala taştığı anlamına gelir; plugin/skill/özel komutları azaltın veya channels.telegram.commands.native seçeneğini devre dışı bırakın.
• Doğrudan Bot API curl komutları çalışırken deleteWebhook, deleteMyCommands veya setMyCommands işleminin 404: Not Found ile başarısız olması, channels.telegram.apiRoot değerinin tam /bot<TOKEN> uç noktasına ayarlandığı anlamına gelebilir. apiRoot yalnızca Bot API kökü olmalıdır ve openclaw doctor --fix yanlışlıkla eklenen sonda /bot<TOKEN> kısmını kaldırır.
• getMe returned 401, Telegram'ın yapılandırılan bot token'ını reddettiği anlamına gelir. botToken, tokenFile veya TELEGRAM_BOT_TOKEN değerini güncel BotFather token'ıyla güncelleyin; OpenClaw yoklamadan önce durur, bu nedenle bu bir Webhook temizleme hatası olarak raporlanmaz.
• Ağ/fetch hatalarıyla setMyCommands failed genellikle api.telegram.org için giden DNS/HTTPS'nin engellendiği anlamına gelir.

Cihaz eşleştirme komutları (device-pair plugin)

device-pair plugin'i yüklendiğinde:

1. /pair kurulum kodu üretir
2. kodu iOS uygulamasına yapıştırın
3. /pair pending bekleyen istekleri listeler (rol/kapsamlar dahil)
4. isteği onaylayın:
   • açık onay için /pair approve <requestId>
   • yalnızca bir bekleyen istek olduğunda /pair approve
   • en yeni için /pair approve latest

Kurulum kodu kısa ömürlü bir bootstrap token'ı taşır. Yerleşik kurulum kodu bootstrap'i, scopes: [] ile dayanıklı bir node token'ı ve güvenilir mobil onboarding için sınırlı bir operatör devretme token'ı döndürür. Bu operatör token'ı kurulum zamanı yerel yapılandırmasını okuyabilir, ancak eşleştirme mutasyon kapsamları veya operator.admin vermez.

Bir cihaz değişmiş kimlik doğrulama ayrıntılarıyla yeniden denerse (örneğin rol/kapsamlar/açık anahtar), önceki bekleyen istek geçersiz kılınır ve yeni istek farklı bir requestId kullanır. Onaylamadan önce /pair pending komutunu yeniden çalıştırın.

Daha fazla ayrıntı: Eşleştirme.

Satır içi klavye kapsamını yapılandırın:

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

Hesap başına geçersiz kılma:

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

Kapsamlar:

• off
• dm
• group
• all
• allowlist (varsayılan)

Eski capabilities: ["inlineButtons"], inlineButtons: "all" değerine eşlenir.

Mesaj eylemi örneği:

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

Mini App düğmesi örneği:

{action: "send",channel: "telegram",to: "123456789",message: "Open app:",presentation: {blocks: [  {    type: "buttons",    buttons: [{ label: "Launch", web_app: { url: "https://example.com/app" } }],  },],},}

Telegram web_app düğmeleri yalnızca bir kullanıcı ile bot arasındaki özel sohbetlerde çalışır.

Kayıtlı bir Plugin etkileşimli işleyicisi tarafından üstlenilmeyen geri çağırma tıklamaları ajana metin olarak iletilir: callback_data: <value>

Telegram araç eylemleri şunları içerir:

• sendMessage (to, content, isteğe bağlı mediaUrl, replyToMessageId, messageThreadId)
• react (chatId, messageId, emoji)
• deleteMessage (chatId, messageId)
• editMessage (chatId, messageId, content veya caption, isteğe bağlı presentation satır içi düğmeleri; yalnızca düğme düzenlemeleri yanıt işaretlemesini günceller)
• createForumTopic (chatId, name, isteğe bağlı iconColor, iconCustomEmojiId)

Kanal mesaj eylemleri ergonomik takma adlar sunar (send, react, delete, edit, sticker, sticker-search, topic-create).

Geçit denetimleri:

• channels.telegram.actions.sendMessage
• channels.telegram.actions.deleteMessage
• channels.telegram.actions.reactions
• channels.telegram.actions.sticker (varsayılan: devre dışı)

Not: edit ve topic-create şu anda varsayılan olarak etkindir ve ayrı channels.telegram.actions.* anahtarları yoktur. Çalışma zamanı gönderimleri etkin yapılandırma/gizli bilgiler anlık görüntüsünü (başlatma/yeniden yükleme) kullanır, bu nedenle eylem yolları her gönderim için geçici SecretRef yeniden çözümlemesi yapmaz.

Tepki kaldırma semantiği: /tools/reactions

Telegram, oluşturulan çıktıda açık yanıt iş parçacığı etiketlerini destekler:

• [[reply_to_current]] tetikleyen mesaja yanıt verir
• [[reply_to:<id>]] belirli bir Telegram mesaj kimliğine yanıt verir

channels.telegram.replyToMode işlemeyi denetler:

• off (varsayılan)
• first
• all

Yanıt iş parçacığı etkinleştirildiğinde ve özgün Telegram metni veya başlığı kullanılabilir olduğunda, OpenClaw otomatik olarak yerel bir Telegram alıntı kesiti ekler. Telegram yerel alıntı metnini 1024 UTF-16 kod birimiyle sınırlar; bu nedenle daha uzun mesajlar baştan alıntılanır ve Telegram alıntıyı reddederse düz yanıta geri döner.

Not: off, örtük yanıt iş parçacığını devre dışı bırakır. Açık [[reply_to_*]] etiketleri yine de uygulanır.

Forum süper grupları:

• konu oturumu anahtarları :topic:<threadId> ekler
• yanıtlar ve yazıyor göstergesi konu iş parçacığını hedefler
• konu yapılandırma yolu: channels.telegram.groups.<chatId>.topics.<threadId>

Genel konu (threadId=1) özel durumu:

• mesaj gönderimleri message_thread_id değerini atlar (Telegram sendMessage(...thread_id=1) çağrısını reddeder)
• yazıyor eylemleri yine de message_thread_id içerir

Konu kalıtımı: konu girdileri geçersiz kılınmadıkça grup ayarlarını devralır (requireMention, allowFrom, skills, systemPrompt, enabled, groupPolicy). agentId yalnızca konuya özeldir ve grup varsayılanlarından devralınmaz. topics."*" o gruptaki her konu için varsayılanları ayarlar; kesin konu kimlikleri yine de "*" üzerinde önceliklidir.

Konu başına ajan yönlendirme: Her konu, konu yapılandırmasında agentId ayarlanarak farklı bir ajana yönlendirilebilir. Bu, her konuya kendi yalıtılmış çalışma alanını, belleğini ve oturumunu verir. Örnek:

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

Ardından her konunun kendi oturum anahtarı olur: agent:zu:telegram:group:-1001234567890:topic:3

Kalıcı ACP konu bağlama: Forum konuları, üst düzey türlenmiş ACP bağlamaları (type: "acp" ve match.channel: "telegram", peer.kind: "group" içeren bindings[] ve -1001234567890:topic:42 gibi konu nitelemeli bir kimlik) üzerinden ACP harness oturumlarını sabitleyebilir. Şu anda gruplardaki/süper gruplardaki forum konularıyla sınırlıdır. Bkz. ACP Ajanları.

Sohbetten iş parçacığına bağlı ACP başlatma: /acp spawn <agent> --thread here|auto geçerli konuyu yeni bir ACP oturumuna bağlar; takip mesajları doğrudan oraya yönlendirilir. OpenClaw başlatma onayını konu içinde sabitler. channels.telegram.threadBindings.spawnSessions etkin kalmalıdır (varsayılan: true).

Şablon bağlamı MessageThreadId ve IsForum değerlerini sunar. message_thread_id içeren DM sohbetleri yanıt meta verilerini korur; yalnızca Telegram getMe bot için has_topics_enabled: true bildirdiğinde iş parçacığı farkındalığı olan oturum anahtarlarını kullanırlar. Önceki dm.threadReplies ve direct.*.threadReplies geçersiz kılmaları bilinçli olarak emekliye ayrıldı; tek doğruluk kaynağı olarak BotFather iş parçacıklı modunu kullanın ve eski yapılandırma anahtarlarını kaldırmak için openclaw doctor --fix çalıştırın.

Sesli mesajlar

Telegram, ses notlarını ses dosyalarından ayırır.

• varsayılan: ses dosyası davranışı
• ses notu gönderimini zorlamak için ajan yanıtında [[audio_as_voice]] etiketi
• gelen ses notu transkriptleri ajan bağlamında makine tarafından oluşturulmuş, güvenilmeyen metin olarak çerçevelenir; bahsetme algılama yine de ham transkripti kullanır, böylece bahsetme geçitli sesli mesajlar çalışmaya devam eder.

Mesaj eylemi örneği:

{action: "send",channel: "telegram",to: "123456789",media: "https://example.com/voice.ogg",asVoice: true,}

Video mesajları

Telegram, video dosyaları ile video notlarını ayırt eder.

Mesaj eylemi örneği:

{action: "send",channel: "telegram",to: "123456789",media: "https://example.com/video.mp4",asVideoNote: true,}

Video notları altyazıları desteklemez; sağlanan mesaj metni ayrı olarak gönderilir.

Çıkartmalar

Gelen çıkartma işleme:

• statik WEBP: indirilir ve işlenir (yer tutucu <media:sticker>)
• animasyonlu TGS: atlanır
• video WEBM: atlanır

Çıkartma bağlam alanları:

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

Çıkartma açıklamaları, tekrarlanan görüntü çağrılarını azaltmak için OpenClaw SQLite plugin durumunda önbelleğe alınır.

Çıkartma eylemlerini etkinleştirin:

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

Çıkartma gönderme eylemi:

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

Önbelleğe alınmış çıkartmaları arayın:

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

Telegram tepkileri, ileti yüklerinden ayrı olarak message_reaction güncellemeleri şeklinde gelir.

Etkinleştirildiğinde OpenClaw şu tür sistem olaylarını kuyruğa alır:

• Telegram reaction added: 👍 by Alice (@alice) on msg 42

Yapılandırma:

• channels.telegram.reactionNotifications: off | own | all (varsayılan: own)
• channels.telegram.reactionLevel: off | ack | minimal | extensive (varsayılan: minimal)

Notlar:

• own, yalnızca bot tarafından gönderilen mesajlara verilen kullanıcı tepkileri anlamına gelir (gönderilmiş mesaj önbelleği üzerinden en iyi çaba).
• Tepki olayları yine de Telegram erişim kontrollerine (dmPolicy, allowFrom, groupPolicy, groupAllowFrom) uyar; yetkisiz gönderenler bırakılır.
• Telegram, tepki güncellemelerinde konu kimlikleri sağlamaz.
  • forum olmayan gruplar grup sohbeti oturumuna yönlendirilir
  • forum grupları, tam kaynak konuya değil, grubun genel konu oturumuna (:topic:1) yönlendirilir

Yoklama/webhook için allowed_updates, message_reaction değerini otomatik olarak içerir.

ackReaction, OpenClaw gelen bir mesajı işlerken bir onay emojisi gönderir. ackReactionScope, bu emojinin gerçekte ne zaman gönderileceğine karar verir.

Emoji (ackReaction) çözümleme sırası:

• channels.telegram.accounts.<accountId>.ackReaction
• channels.telegram.ackReaction
• messages.ackReaction
• aracı kimliği emoji yedeği (agents.list[].identity.emoji, aksi halde "👀")

Notlar:

• Telegram unicode emoji bekler (örneğin "👀").
• Bir kanal veya hesap için tepkiyi devre dışı bırakmak üzere "" kullanın.

Kapsam (messages.ackReactionScope):

Telegram sağlayıcısı kapsamı messages.ackReactionScope değerinden okur (varsayılan "group-mentions"). Bugün Telegram hesabı veya Telegram kanalı düzeyinde geçersiz kılma yoktur.

Değerler: "all" (DM'ler + gruplar), "direct" (yalnızca DM'ler), "group-all" (her grup mesajı, DM yok), "group-mentions" (bot belirtildiğinde gruplar; DM yok — varsayılan budur), "off" / "none" (devre dışı).

Kanal yapılandırma yazımları varsayılan olarak etkindir (configWrites !== false).

Telegram tarafından tetiklenen yazımlar şunları içerir:

• channels.telegram.groups değerini güncellemek için grup taşıma olayları (migrate_to_chat_id)
• /config set ve /config unset (komut etkinleştirmesi gerektirir)

Devre dışı bırakma:

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

Varsayılan uzun yoklamadır. Webhook modu için channels.telegram.webhookUrl ve channels.telegram.webhookSecret değerlerini ayarlayın; isteğe bağlı webhookPath, webhookHost, webhookPort (varsayılanlar /telegram-webhook, 127.0.0.1, 8787).

Uzun yoklama modunda OpenClaw, yeniden başlatma filigranını yalnızca bir güncelleme başarıyla dağıtıldıktan sonra kalıcı hale getirir. Bir işleyici başarısız olursa, bu güncelleme aynı süreçte yeniden denenebilir durumda kalır ve yeniden başlatma tekilleştirmesi için tamamlandı olarak yazılmaz.

Yerel dinleyici 127.0.0.1:8787 adresine bağlanır. Herkese açık giriş için yerel bağlantı noktasının önüne bir ters proxy koyun ya da bilinçli olarak webhookHost: "0.0.0.0" ayarlayın.

Webhook modu, Telegram'a 200 döndürmeden önce istek korumalarını, Telegram gizli belirtecini ve JSON gövdesini doğrular. Ardından OpenClaw güncellemeyi, uzun yoklamanın kullandığı aynı sohbet başına/konu başına bot hatları üzerinden eşzamansız olarak işler; böylece yavaş aracı turları Telegram'ın teslim ACK'sini bekletmez.

• channels.telegram.textChunkLimit varsayılanı 4000'dir.
• channels.telegram.chunkMode="newline", uzunluğa göre bölmeden önce paragraf sınırlarını (boş satırlar) tercih eder.
• channels.telegram.mediaMaxMb (varsayılan 100), gelen ve giden Telegram medya boyutunu sınırlar.
• channels.telegram.mediaGroupFlushMs (varsayılan 500), Telegram albümlerinin/medya gruplarının OpenClaw tarafından tek bir gelen mesaj olarak gönderilmeden önce ne kadar süre arabelleğe alınacağını kontrol eder. Albüm parçaları geç geliyorsa artırın; albüm yanıt gecikmesini azaltmak için düşürün.
• channels.telegram.timeoutSeconds, Telegram API istemcisi zaman aşımını geçersiz kılar (ayarlanmamışsa grammY varsayılanı uygulanır). Bot istemcileri, yapılandırılan değerleri 60 saniyelik giden metin/yazıyor isteği korumasının altında sınırlayarak grammY'nin OpenClaw'ın taşıma koruması ve geri dönüşü çalışmadan önce görünür yanıt teslimini iptal etmesini önler. Uzun yoklama hâlâ 45 saniyelik bir getUpdates isteği koruması kullanır, böylece boşta kalan yoklamalar süresiz olarak terk edilmez.
• channels.telegram.pollingStallThresholdMs varsayılan olarak 120000 değerindedir; yalnızca yanlış pozitif yoklama takılması yeniden başlatmaları için 30000 ile 600000 arasında ayarlayın.
• grup bağlam geçmişi channels.telegram.historyLimit veya messages.groupChat.historyLimit (varsayılan 50) kullanır; 0 devre dışı bırakır.
• yanıt/alıntı/iletme ek bağlamı, Gateway üst mesajları gözlemlediğinde seçili tek bir konuşma bağlamı penceresine normalleştirilir; gözlemlenen mesaj önbelleği OpenClaw SQLite Plugin durumunda bulunur ve openclaw doctor --fix eski yan dosyaları içe aktarır. Telegram güncellemelerde yalnızca tek bir sığ reply_to_message içerir, bu yüzden önbellekten daha eski zincirler Telegram'ın mevcut güncelleme yüküyle sınırlıdır.
• Telegram izin listeleri öncelikli olarak agent'ı kimin tetikleyebileceğini denetler; tam bir ek bağlam redaksiyon sınırı değildir.
• DM geçmişi denetimleri:
  • channels.telegram.dmHistoryLimit
  • channels.telegram.dms["<user_id>"].historyLimit
• channels.telegram.retry yapılandırması, kurtarılabilir giden API hataları için Telegram gönderme yardımcılarına (CLI/araçlar/eylemler) uygulanır. Gelen son yanıt teslimi de Telegram bağlantı öncesi hataları için sınırlı güvenli gönderme yeniden denemesi kullanır, ancak görünür mesajları çoğaltabilecek belirsiz gönderim sonrası ağ zarflarını yeniden denemez.

CLI ve mesaj aracı gönderme hedefleri sayısal sohbet kimliği, kullanıcı adı veya forum konusu hedefi olabilir:

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"

Telegram yoklamaları openclaw message poll kullanır ve forum konularını destekler:

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

Yalnızca Telegram yoklama bayrakları:

• --poll-duration-seconds (5-600)
• --poll-anonymous
• --poll-public
• forum konuları için --thread-id (veya bir :topic: hedefi kullanın)

Telegram gönderimi ayrıca şunları destekler:

• channels.telegram.capabilities.inlineButtons izin verdiğinde satır içi klavyeler için buttons bloklarıyla --presentation
• bot o sohbette sabitleyebildiğinde sabitlenmiş teslim istemek için --pin veya --delivery '{"pin":true}'
• giden görselleri, GIF'leri ve videoları sıkıştırılmış fotoğraf, animasyonlu medya veya video yüklemeleri yerine belge olarak göndermek için --force-document

Eylem denetimi:

• channels.telegram.actions.sendMessage=false, yoklamalar dahil giden Telegram mesajlarını devre dışı bırakır
• channels.telegram.actions.poll=false, normal gönderimleri etkin bırakırken Telegram yoklaması oluşturmayı devre dışı bırakır

Telegram, onaylayıcı DM'lerinde exec onaylarını destekler ve isteğe bağlı olarak istemleri kaynak sohbete veya konuya gönderebilir. Onaylayıcılar sayısal Telegram kullanıcı kimlikleri olmalıdır.

Yapılandırma yolu:

• channels.telegram.execApprovals.enabled (en az bir onaylayıcı çözümlenebildiğinde otomatik etkinleşir)
• channels.telegram.execApprovals.approvers (commands.ownerAllowFrom içindeki sayısal sahip kimliklerine geri döner)
• channels.telegram.execApprovals.target: dm (varsayılan) | channel | both
• agentFilter, sessionFilter

channels.telegram.allowFrom, groupAllowFrom ve defaultTo, botla kimin konuşabileceğini ve normal yanıtları nereye göndereceğini kontrol eder. Birini exec onaylayıcısı yapmazlar. İlk onaylanmış DM eşleştirmesi, henüz komut sahibi yoksa commands.ownerAllowFrom öğesini başlatır; böylece tek sahipli kurulum, kimlikleri execApprovals.approvers altında çoğaltmadan çalışmaya devam eder.

Kanal teslimi komut metnini sohbette gösterir; channel veya both seçeneklerini yalnızca güvenilir gruplarda/konularda etkinleştirin. İstem bir forum konusuna düştüğünde OpenClaw onay istemi ve devamı için konuyu korur. Exec onayları varsayılan olarak 30 dakika sonra sona erer.

Satır içi onay düğmeleri ayrıca channels.telegram.capabilities.inlineButtons öğesinin hedef yüzeye (dm, group veya all) izin vermesini gerektirir. plugin: ön ekiyle başlayan onay kimlikleri Plugin onayları üzerinden çözümlenir; diğerleri önce exec onayları üzerinden çözümlenir.

Bkz. Exec onayları.

• requireMention=false ise Telegram gizlilik modu tam görünürlüğe izin vermelidir.
  • BotFather: /setprivacy -> Devre dışı bırak
  • ardından botu gruptan çıkarıp yeniden ekleyin
• openclaw channels status, yapılandırma bahsedilmeyen grup mesajları beklediğinde uyarır.
• openclaw channels status --probe açık sayısal grup kimliklerini denetleyebilir; joker karakter "*" için üyelik yoklaması yapılamaz.
• hızlı oturum testi: /activation always.

• channels.telegram.groups varsa grup listelenmelidir (veya "*" içermelidir)
• botun gruptaki üyeliğini doğrulayın
• atlama nedenleri için günlükleri inceleyin: openclaw logs --follow

• gönderen kimliğinizi yetkilendirin (eşleştirme ve/veya sayısal allowFrom)
• grup politikası open olsa bile komut yetkilendirmesi hâlâ uygulanır
• BOT_COMMANDS_TOO_MUCH ile setMyCommands failed, yerel menüde çok fazla giriş olduğu anlamına gelir; Plugin/skill/özel komutları azaltın veya yerel menüleri devre dışı bırakın
• deleteMyCommands / setMyCommands başlangıç çağrıları ve sendChatAction yazıyor çağrıları sınırlıdır ve istek zaman aşımında Telegram'ın taşıma geri dönüşü üzerinden bir kez yeniden denenir. Kalıcı ağ/fetch hataları genellikle api.telegram.org için DNS/HTTPS erişilebilirliği sorunlarını gösterir

• getMe returned 401, yapılandırılan bot token'ı için bir Telegram kimlik doğrulama hatasıdır.
• BotFather'da bot token'ını yeniden kopyalayın veya yeniden oluşturun, ardından varsayılan hesap için channels.telegram.botToken, channels.telegram.tokenFile, channels.telegram.accounts.<id>.botToken veya TELEGRAM_BOT_TOKEN öğesini güncelleyin.
• Başlangıç sırasında deleteWebhook 401 Unauthorized da bir kimlik doğrulama hatasıdır; bunu "webhook yok" olarak ele almak, aynı hatalı token sorununu yalnızca sonraki API çağrılarına ertelemiş olur.

• Node 22+ ve özel fetch/proxy, AbortSignal türleri uyuşmazsa anında iptal davranışını tetikleyebilir.
• Bazı ana makineler api.telegram.org adresini önce IPv6'ya çözümler; bozuk IPv6 çıkışı aralıklı Telegram API hatalarına neden olabilir.
• Günlükler TypeError: fetch failed veya Network request for 'getUpdates' failed! içeriyorsa, OpenClaw artık bunları kurtarılabilir ağ hataları olarak yeniden dener.
• Yoklama başlangıcı sırasında OpenClaw, grammY için başarılı başlangıç getMe yoklamasını yeniden kullanır, böylece çalıştırıcının ilk getUpdates öncesinde ikinci bir getMe çağrısına ihtiyacı olmaz.
• Yoklama başlangıcı sırasında deleteWebhook geçici bir ağ hatasıyla başarısız olursa OpenClaw başka bir yoklama öncesi denetim düzlemi çağrısı yapmak yerine uzun yoklamaya devam eder. Hâlâ etkin olan bir webhook getUpdates çakışması olarak görünür; ardından OpenClaw Telegram taşımasını yeniden oluşturur ve webhook temizliğini yeniden dener.
• Telegram soketleri kısa ve sabit bir ritimde yeniden oluşturuluyorsa düşük bir channels.telegram.timeoutSeconds olup olmadığını denetleyin; bot istemcileri yapılandırılmış değerleri giden ve getUpdates isteği korumalarının altında sınırlar, ancak eski sürümler bu değer korumaların altına ayarlandığında her yoklamayı veya yanıtı iptal edebiliyordu.
• Günlükler Polling stall detected içeriyorsa OpenClaw, varsayılan olarak tamamlanmış uzun yoklama canlılığı olmadan geçen 120 saniyeden sonra yoklamayı yeniden başlatır ve Telegram taşımasını yeniden oluşturur.
• openclaw channels status --probe ve openclaw doctor, çalışan bir yoklama hesabı başlangıç toleransından sonra getUpdates tamamlamadığında, çalışan bir webhook hesabı başlangıç toleransından sonra setWebhook tamamlamadığında veya son başarılı yoklama taşıma etkinliği bayatladığında uyarır.
• channels.telegram.pollingStallThresholdMs değerini yalnızca uzun süre çalışan getUpdates çağrıları sağlıklı olduğu halde ana makineniz hâlâ yanlış yoklama takılması yeniden başlatmaları bildiriyorsa artırın. Kalıcı takılmalar genellikle ana makine ile api.telegram.org arasındaki proxy, DNS, IPv6 veya TLS çıkış sorunlarına işaret eder.
• Telegram ayrıca Bot API taşıması için HTTP_PROXY, HTTPS_PROXY, ALL_PROXY ve bunların küçük harfli varyantları dahil süreç proxy ortam değişkenlerini dikkate alır. NO_PROXY / no_proxy yine de api.telegram.org için proxy'yi atlayabilir.
• OpenClaw yönetimli proxy bir hizmet ortamı için OPENCLAW_PROXY_URL üzerinden yapılandırılmışsa ve standart proxy ortam değişkeni yoksa Telegram da Bot API taşıması için bu URL'yi kullanır.
• Kararsız doğrudan çıkış/TLS olan VPS ana makinelerinde Telegram API çağrılarını channels.telegram.proxy üzerinden yönlendirin:

channels:telegram:proxy: socks5://<user>:<password>@proxy-host:1080

• Node 22+ varsayılan olarak autoSelectFamily=true kullanır (WSL2 hariç). Telegram DNS sonuç sırası önce OPENCLAW_TELEGRAM_DNS_RESULT_ORDER, ardından channels.telegram.network.dnsResultOrder, ardından NODE_OPTIONS=--dns-result-order=ipv4first gibi süreç varsayılanını izler; hiçbiri geçerli değilse Node 22+ ipv4first değerine geri döner.
• Ana makineniz WSL2 ise veya açıkça yalnızca IPv4 davranışıyla daha iyi çalışıyorsa, aile seçimini zorlayın:

channels:telegram:network:  autoSelectFamily: false

• RFC 2544 kıyaslama aralığı yanıtlarına (198.18.0.0/15) Telegram medya indirmeleri için varsayılan olarak zaten izin verilir. Güvenilir bir fake-IP veya saydam proxy, medya indirmeleri sırasında api.telegram.org adresini başka bir özel/dahili/özel kullanımlı adrese yeniden yazıyorsa, yalnızca Telegram'a özgü bypass'ı etkinleştirebilirsiniz:

channels:telegram:network:  dangerouslyAllowPrivateNetwork: true

• Aynı etkinleştirme, hesap başına channels.telegram.accounts.<accountId>.network.dangerouslyAllowPrivateNetwork konumunda da kullanılabilir.
• Proxy'niz Telegram medya ana makinelerini 198.18.x.x adreslerine çözümlüyorsa, önce tehlikeli bayrağı kapalı bırakın. Telegram medyası RFC 2544 kıyaslama aralığına varsayılan olarak zaten izin verir.

• Ortam geçersiz kılmaları (geçici):
  • OPENCLAW_TELEGRAM_DISABLE_AUTO_SELECT_FAMILY=1
  • OPENCLAW_TELEGRAM_ENABLE_AUTO_SELECT_FAMILY=1
  • OPENCLAW_TELEGRAM_DNS_RESULT_ORDER=ipv4first
• DNS yanıtlarını doğrulayın:

dig +short api.telegram.org Adig +short api.telegram.org AAAA