Telegram

Telegram botları varsayılan olarak Privacy Mode kullanır; bu, hangi grup mesajlarını alabileceklerini sınırlar.

Tüm grup mesajlarını görmek için şunlardan birini yapın:

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

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

Yönetici durumu Telegram grup ayarlarından denetlenir. Yönetici botlar tüm grup mesajlarını alır; bu, sürekli etkin grup davranışı için yararlıdır.

• /setjoingroups — gruplara eklemeye izin ver/reddet
• /setprivacy — grup görünürlüğü davranışı

Sohbet komutları yerine kullanıcı arayüzünü tercih ediyorsanız aynı ayarlar BotFather'ın web uygulamasında da bulunur.

OpenClaw, doğrudan sohbetlerde, gruplarda ve konularda kısmi yanıtları gerçek zamanlı olarak yayımlar: bir önizleme iletisi gönderir, ardından editMessageText işlemini art arda gerçekleştirerek yerinde sonlandırır.

• channels.telegram.streaming, off | partial | block | progress değerindedir (varsayılan: partial)
• kısa ilk yanıt önizlemelerine geri sekme uygulanır; ardından çalıştırma hâlâ etkinse sınırlı bir gecikmeden sonra somutlaştırılır
• progress, araç ilerlemesi için düzenlenebilir tek bir durum taslağını korur; yanıt etkinliği araç ilerlemesinden önce geldiğinde kararlı durum etiketini gösterir, tamamlandığında taslağı temizler ve son yanıtı normal bir ileti olarak gönderir
• streaming.preview.toolProgress, araç/ilerleme güncellemelerinin aynı düzenlenmiş önizleme iletisini yeniden kullanıp kullanmayacağını denetler (varsayılan: önizleme akışı etkinken true)
• streaming.preview.commandText, bu satırlardaki komut/yürütme ayrıntısını denetler: raw (varsayılan) veya status (yalnızca araç etiketi)
• streaming.progress.commentary (varsayılan: false), geçici ilerleme taslağında asistan açıklaması/giriş metnini etkinleştirir
• eski channels.telegram.streamMode, mantıksal streaming değerleri ve kullanımdan kaldırılmış yerel taslak önizleme anahtarları algılanır; bunları taşımak için openclaw doctor --fix çalıştırın

Araç ilerleme satırları, araçlar çalışırken gösterilen kısa durum güncellemeleridir (komut yürütme, dosya okuma, planlama güncellemeleri, yama özetleri, uygulama sunucusu modunda Codex girişleri/açıklamaları). Telegram bunları varsayılan olarak açık tutar (v2026.4.22+ sürümünden itibaren yayımlanan davranışla eşleşir).

Yanıt önizleme düzenlemelerini koruyup araç ilerleme satırlarını gizleyin:

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

Araç ilerlemesini görünür tutup komut/yürütme metnini gizleyin:

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

progress modu, son yanıtı bu iletinin içine düzenlemeden araç ilerlemesini gösterir. Komut metni ilkesini streaming.progress altına yerleştirin:

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

streaming.mode: "off", önizleme düzenlemelerini devre dışı bırakır ve genel araç/ilerleme bildirimlerini bağımsız durum iletileri olarak göndermek yerine bastırır; onay istemleri, medya ve hatalar yine normal son teslim yoluyla yönlendirilir. streaming.preview.toolProgress: false yalnızca yanıt önizleme düzenlemelerini korur.

Yalnızca metin içeren yanıtlar için: kısa önizlemelerde son düzenleme yerinde yapılır; birden fazla iletiye bölünen uzun son yanıtlar önizlemeyi ilk parça olarak yeniden kullanır, ardından yalnızca kalan kısmı gönderir; ilerleme modu son yanıtları durum taslağını temizleyip normal son teslimi kullanır; tamamlanma onaylanmadan önce son düzenleme başarısız olursa OpenClaw normal son teslime geri döner ve eski önizlemeyi temizler. Karmaşık yanıtlar (medya yükleri) için OpenClaw her zaman normal son teslime geri döner ve önizlemeyi temizler.

Önizleme akışı ile blok akışı birbirini dışlar — blok akışı açıkça etkinleştirildiğinde OpenClaw çift akışı önlemek için önizleme akışını atlar.

Akıl yürütme: /reasoning stream, oluşturma sırasında akıl yürütmeyi canlı önizlemeye aktarır ve son teslimden sonra akıl yürütme önizlemesini siler (görünür tutmak için /reasoning on kullanın). Son yanıt, akıl yürütme metni olmadan gönderilir.

Giden metin varsayılan olarak güncel istemcilerde okunabilen standart Telegram HTML iletilerini kullanır: kalın, italik, bağlantılar, kod, spoiler'lar, alıntılar — Bot API 10.2'ye özgü zengin bloklar (yerel tablolar, ayrıntılar, zengin medya, formüller) değil.

Bot API 10.2 zengin iletilerini etkinleştirin:

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

Etkinleştirildiğinde: aracıya bu bot/hesap için zengin iletilerin kullanılabildiği bildirilir (desteklenen Markdown + HTML adacığı yazım sözleşmesiyle birlikte); Markdown metni, OpenClaw'ın Markdown IR'si üzerinden türü belirlenmiş Bot API 10.2 zengin blokları (başlıklar, tablolar, ayrıntılar, denetim listeleri, zengin medya, formüller, haritalar, kolajlar) olarak işlenir; medya açıklamaları yine Telegram HTML açıklamalarını kullanır (zengin iletiler açıklamaların yerini almaz ve açıklamalar en fazla 1024 karakter olabilir).

Bu, model metnini Telegram'ın zengin Markdown işaretlerinden uzak tutar; böylece $400-600K gibi para birimleri matematik olarak ayrıştırılmaz. Uzun zengin metin, Telegram'ın sınırlarına göre otomatik olarak bölünür. 20 sütun sınırını aşan tablolar kod bloğuna geri döner.

Varsayılan: istemci uyumluluğu için kapalıdır — bazı güncel Masaüstü, Web, Android ve üçüncü taraf istemciler kabul edilen zengin iletileri desteklenmiyor olarak işler. Botla kullanılan her istemci bunları işleyemiyorsa bu özelliği kapalı tutun. /status, geçerli oturumda zengin iletilerin açık mı kapalı mı olduğunu gösterir.

Bağlantı önizlemeleri varsayılan olarak açıktır. channels.telegram.linkPreview: false, zengin metin için otomatik varlık algılamayı devre dışı bırakır.

Telegram'ın komut menüsü, başlatma sırasında setMyCommands ile kaydedilir. commands.native: "auto", Telegram için yerel komutları etkinleştirir.

Özel komut menüsü girdileri ekleyin:

{channels: {telegram: {  customCommands: [    { command: "backup", description: "Git yedeklemesi" },    { command: "generate", description: "Görsel oluştur" },  ],},},}

Kurallar: adlar normalleştirilir (baştaki / kaldırılır, küçük harfe dönüştürülür); 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 kaydedilir.

Özel komutlar yalnızca menü girdileridir — davranışı otomatik olarak uygulamazlar. Plugin/skill komutları, Telegram menüsünde gösterilmese bile yazıldıklarında çalışmaya devam edebilir. Yerel komutlar devre dışıysa yerleşik komutlar kaldırılır; özel/Plugin komutları yapılandırılmışsa yine kaydedilebilir.

Yaygın kurulum hataları:

• Kırpma yeniden denemesinden sonra BOT_COMMANDS_TOO_MUCH içeren setMyCommands failed, menünün hâlâ sınırı aştığı anlamına gelir; Plugin/skill/özel komutları azaltın veya channels.telegram.commands.native özelliğ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ı genellikle channels.telegram.apiRoot değerinin tam /bot<TOKEN> uç noktasına ayarlandığı anlamına gelir. apiRoot yalnızca Bot API kökü olmalıdır; openclaw doctor --fix, yanlışlıkla eklenmiş sondaki /bot<TOKEN> bölümünü kaldırır.
• getMe returned 401, Telegram'ın yapılandırılan bot belirtecini reddettiği anlamına gelir. botToken, tokenFile veya TELEGRAM_BOT_TOKEN (varsayılan hesap) değerini geçerli BotFather belirteciyle güncelleyin; OpenClaw yoklamadan önce durduğu için bu durum Webhook temizleme hatası olarak bildirilmez.
• Ağ/getirme hataları içeren setMyCommands failed genellikle api.telegram.org adresine giden DNS/HTTPS trafiğinin engellendiği anlamına gelir.

Cihaz eşleştirme komutları (device-pair Plugin'i)

Kurulduğunda:

1. /pair bir kurulum kodu oluşturur
2. kodu iOS uygulamasına yapıştırın
3. /pair pending bekleyen istekleri listeler (rol/kapsamlar dâhil)
4. onaylama: /pair approve <requestId>, /pair approve (yalnızca bekleyen istek) veya /pair approve latest

Bir cihaz değiştirilmiş kimlik doğrulama ayrıntılarıyla (rol, kapsamlar, ortak anahtar) yeniden denerse önceki bekleyen isteğin yerini yeni bir requestId alı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"], "all" değerine eşlenir.

İleti eylemi örneği:

{action: "send",channel: "telegram",to: "123456789",message: "Bir seçenek belirleyin:",buttons: [[  { text: "Evet", callback_data: "yes" },  { text: "Hayır", callback_data: "no" },],[{ text: "İptal", callback_data: "cancel" }],],}

Mini Uygulama düğmesi örneği:

{action: "send",channel: "telegram",to: "123456789",message: "Uygulamayı açın:",presentation: {blocks: [  {    type: "buttons",    buttons: [{ label: "Başlat", web_app: { url: "https://example.com/app" } }],  },],},}

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 sahiplenilmeyen geri çağırma tıklamaları aracıya metin olarak iletilir: callback_data: <value>.

Eylemler:

• 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)

Kullanışlı takma adlar: send, react, delete, edit, sticker, sticker-search, topic-create.

Etkinleştirme koşulları: channels.telegram.actions.sendMessage, deleteMessage, reactions, sticker (varsayılan: devre dışı). edit, createForumTopic ve editForumTopic, özel bir geçiş anahtarı olmadan varsayılan olarak etkindir. Çalışma zamanı gönderimleri, başlangıçta/yeniden yüklemede alınan etkin yapılandırma/gizli bilgiler anlık görüntüsünü kullanır; bu nedenle eylem yolları her gönderimde SecretRef değerlerini yeniden çözümlemez.

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

Oluşturulan çıktıdaki açık yanıt iş parçacığı etiketleri:

• [[reply_to_current]] — tetikleyici iletiyi yanıtlar
• [[reply_to:<id>]] — belirli bir ileti kimliğini yanıtlar

channels.telegram.replyToMode: off (varsayılan), first, all.

Yanıt iş parçacığı etkinleştirildiğinde ve özgün metin/açıklama mevcut olduğunda OpenClaw, otomatik olarak yerel bir alıntı kesiti ekler. Telegram, yerel alıntı metnini 1024 UTF-16 kod birimiyle sınırlar; daha uzun iletiler baştan itibaren alıntılanır ve Telegram alıntıyı reddederse düz yanıta geri dönülür.

off yalnızca örtük yanıt iş parçacığını devre dışı bırakır; açık [[reply_to_*]] etiketleri yine de dikkate alınır.

Forum süper grupları: konu oturumu anahtarlarının sonuna :topic:<threadId> eklenir; yanıtlar ve yazıyor göstergesi konu iş parçacığını hedefler; konu yapılandırma yolu channels.telegram.groups.<chatId>.topics.<threadId> şeklindedir.

Genel konu (threadId=1) özel bir durumdur: ileti gönderimlerinde message_thread_id kullanılmaz (Telegram, sendMessage(...thread_id=1) değerini "iş parçacığı bulunamadı" hatasıyla reddeder), ancak yazıyor eylemleri yine de message_thread_id içerir (yazıyor göstergesinin görünmesi için deneysel olarak gerekli olduğu belirlenmiştir).

Konu girdileri, geçersiz kılınmadığı sürece 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ı belirler; tam konu kimlikleri yine de "*" değerine göre önceliklidir.

Konu başına agent yönlendirmesi: Her konu, konu yapılandırmasındaki agentId aracılığıyla farklı bir agent'a yönlendirilebilir; böylece kendine ait bir çalışma alanına, belleğe ve oturuma sahip olur:

{  channels: {    telegram: {      groups: {        "-1001234567890": {          topics: {            "1": { agentId: "main" },      // Genel konu -> ana agent            "3": { agentId: "zu" },        // Geliştirme konusu -> zu agent'ı            "5": { agentId: "coder" }      // Kod incelemesi -> coder agent'ı          }        }      }    }  }}

Ardından her konunun kendi oturum anahtarı olur; örneğin agent:zu:telegram:group:-1001234567890:topic:3.

Kalıcı ACP konu bağlama: Forum konuları, üst düzey türü belirlenmiş bağlamalar aracılığıyla ACP çalıştırma düzeneği oturumlarını sabitleyebilir (bindings[]; type: "acp", match.channel: "telegram", peer.kind: "group" ve -1001234567890:topic:42 gibi konu nitelemeli bir kimlikle). Şu anda gruplardaki/süper gruplardaki forum konularıyla sınırlıdır. Bkz. ACP Agent'ları.

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; devam iletileri doğrudan buraya yönlendirilir ve OpenClaw, başlatma onayını konu içinde sabitler. session.threadBindings.spawnSessions tarafından denetlenir (varsayılan: true).

Şablon bağlamı, MessageThreadId ve IsForum değerlerini kullanıma sunar. message_thread_id içeren DM sohbetleri yanıt meta verilerini korur, ancak yalnızca Telegram getMe, has_topics_enabled: true bildirdiğinde iş parçacığına duyarlı oturum anahtarlarını kullanır. Kullanımdan kaldırılan dm.threadReplies ve direct.*.threadReplies geçersiz kılmaları kaldırılmıştır; BotFather iş parçacığı modu tek doğruluk kaynağıdır. Eski yapılandırma anahtarlarını kaldırmak için openclaw doctor --fix çalıştırın.

Sesli iletiler

Telegram, sesli notları ses dosyalarından ayırır. Varsayılan: ses dosyası davranışı; sesli not olarak göndermeyi zorlamak için agent yanıtında [[audio_as_voice]] etiketini kullanın. Gelen sesli not dökümleri, agent bağlamında makine tarafından oluşturulmuş ve güvenilmeyen metin olarak çerçevelenir; ancak bahsetme algılaması yine de ham dökümü kullanır, böylece bahsetme koşullu sesli iletiler çalışmaya devam eder.

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

Görüntülü iletiler

Telegram, video dosyalarını görüntülü notlardan ayırır. Görüntülü notlar açıklamaları desteklemez; sağlanan ileti metni ayrı olarak gönderilir.

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

Konumlar ve mekânlar

Tek bir bağımsız location nesnesiyle mevcut send eylemini kullanın. Koordinatlar yerel bir konum işareti gönderir; hem name hem de address eklendiğinde yerel bir mekân kartı gönderilir. Konum gönderimleri, ileti metni veya medyayla birleştirilemez.

{action: "send",channel: "telegram",to: "123456789",location: {latitude: 48.858844,longitude: 2.294351,accuracy: 12,name: "Eiffel Kulesi",address: "Champ de Mars, Paris",},}

Çıkartmalar

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

Çıkartma bağlamı alanları: Sticker.emoji, Sticker.setName, Sticker.fileId, Sticker.fileUniqueId, Sticker.cachedDescription. Tekrarlanan görüntü çağrılarını azaltmak için açıklamalar, OpenClaw SQLite Plugin durumunda önbelleğe alınır.

Çıkartma eylemlerini etkinleştirin:

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

Gönderin:

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

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

{action: "sticker-search",channel: "telegram",query: "el sallayan kedi",limit: 5,}

Telegram tepkileri, ileti yüklerinden ayrı olarak message_reaction güncellemeleri biçiminde gelir. Etkinleştirildiğinde OpenClaw, Telegram reaction added: 👍 by Alice (@alice) on msg 42 gibi sistem olaylarını kuyruğa alır.

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

own, yalnızca bot tarafından gönderilen iletilere yönelik kullanıcı tepkileri anlamına gelir (gönderilen ileti önbelleği aracılığıyla azami gayret esasına göre). Tepki olayları, Telegram erişim denetimlerine (dmPolicy, allowFrom, groupPolicy, groupAllowFrom) yine de uyar; yetkisiz göndericiler yok sayılır.

Telegram, tepki güncellemelerinde iş parçacığı kimliklerini sağlamaz: forum dışı gruplar grup sohbeti oturumuna; forum gruplarıysa tam kaynak konuya değil, 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 iletiyi işlerken bir alındı emojisi gönderir. messages.ackReactionScope, bunun ne zaman gönderileceğini belirler.

Emoji çözümleme sırası:

• channels.telegram.accounts.<accountId>.ackReaction
• channels.telegram.ackReaction
• messages.ackReaction
• agent kimliği emojisi geri dönüşü (agents.entries.*.identity.emoji, aksi takdirde "👀")

Telegram bir Unicode emojisi (örneğin "👀") bekler; bir kanal veya hesap için tepkiyi devre dışı bırakmak üzere "" kullanın.

Kapsam (messages.ackReactionScope, varsayılan "group-mentions"; şu anda Telegram hesabı veya Telegram kanalı geçersiz kılması yoktur):

all (DM'ler + gruplar, ortam odası olayları dâhil), direct (yalnızca DM'ler), group-all (ortam odası olayları hariç tüm grup iletileri, DM yok), group-mentions (bottan bahsedildiğinde gruplar; DM yok — varsayılan), off / none (devre dışı).

Kanal yapılandırması yazma işlemleri varsayılan olarak etkindir (configWrites !== false). Telegram tarafından tetiklenen yazma işlemleri; grup taşıma olaylarını (migrate_to_chat_id, channels.telegram.groups değerini günceller) ve /config set / /config unset işlemlerini (komutun etkinleştirilmesini gerektirir) içerir.

Devre dışı bırakın:

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

Varsayılan, uzun yoklamadır. Webhook modu için channels.telegram.webhookUrl ve channels.telegram.webhookSecret ayarlayın; isteğe bağlı olarak webhookPath (varsayılan /telegram-webhook), webhookHost (varsayılan 127.0.0.1), webhookPort (varsayılan 8787), webhookCertPath (doğrudan IP veya alan adsız kurulumlar için kendinden imzalı sertifika PEM'i) ayarlanabilir.

Uzun yoklama modunda OpenClaw, yeniden başlatma filigranını yalnızca bir güncelleme başarıyla gönderildikten sonra kalıcılaştırır; başarısız bir işleyici, söz konusu güncellemeyi tamamlandı olarak işaretlemek yerine aynı süreçte yeniden denenebilir durumda bırakır.

Yerel dinleyici varsayılan olarak 127.0.0.1:8787 adresine bağlanır. Genel erişim için yerel bağlantı noktasının önüne bir ters proxy yerleştirin veya webhookHost: "0.0.0.0" değerini bilinçli olarak ayarlayın.

Webhook modu istek korumalarını, Telegram gizli belirtecini ve JSON gövdesini doğrular; ardından boş bir 200 döndürmeden önce güncellemeyi dayanıklı giriş kuyruğuna kaydeder. Başarılı dayanıklı kabul işlemi x-openclaw-delivery-accepted: durable içerir; sağlık, yönlendirme, kimlik doğrulama, doğrulama ve depolama hatası yanıtlarında bu üstbilgi bulunmaz. Ters proxy'ler ve ana makine denetleyicileri, kabulü yanıt zamanlamasından çıkarsamadan OpenClaw kabulünü genel bir boş 200 yanıtından ayırt etmek için bu üstbilgiyi zorunlu tutabilir.

Dayanıklı yazma işleminden sonra OpenClaw, güncellemeleri çekirdek kanal girişi boşaltma mekanizması üzerinden talep eder ve işler (sohbet/konu başına işlem hatları, tur kabulünde tamamlama, kabul öncesi duraklama zaman aşımı). Yavaş agent turları Telegram'ın teslimat ACK'sini bekletmez.

• channels.telegram.textChunkLimit varsayılan olarak 4000'dir; streaming.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 medya boyutunu sınırlar.
• 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ı penceresinde normalleştirilir; gözlemlenen mesaj önbelleği OpenClaw SQLite Plugin durumunda tutulur ve openclaw doctor --fix eski yan dosyaları içe aktarır. Telegram, güncelleme başına yalnızca bir sığ reply_to_message içerdiğinden, önbellekten daha eski zincirler bu yükle sınırlıdır.
• Telegram izin listeleri esas olarak ek bağlam için tam bir sansürleme sınırı oluşturmayı değil, aracıyı kimlerin tetikleyebileceğini denetler.
• DM geçmişi: channels.telegram.dmHistoryLimit, channels.telegram.dms["<user_id>"].historyLimit.

CLI ve mesaj aracı gönderme hedefleri; sayısal sohbet kimliğini, kullanıcı adını veya forum konusu hedefini kabul eder:

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"

Anketler 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'a özgü anket bayrakları: --poll-duration-seconds (5-600), --poll-anonymous, --poll-public, --thread-id (veya bir :topic: hedefi). --poll-option, 2-12 kez tekrarlar (Telegram'ın seçenek sınırı).

Telegram gönderimi ayrıca satır içi klavyeler için buttons bloklarıyla --presentation seçeneğini (channels.telegram.capabilities.inlineButtons izin verdiğinde), bot ilgili sohbette sabitleme yapabiliyorsa sabitlenmiş teslimat istemek için --pin veya --delivery '{"pin":true}' seçeneğini ve giden görüntüleri, GIF'leri ve videoları sıkıştırılmış/animasyonlu/video yüklemeleri yerine belge olarak göndermek için --force-document seçeneğini destekler.

Eylem denetimi: channels.telegram.actions.sendMessage=false, anketler dâhil tüm giden mesajları devre dışı bırakır; channels.telegram.actions.poll=false, normal gönderimleri etkin bırakırken anket oluşturmayı devre dışı bırakır.

Telegram, onaylayıcıların DM'lerinde exec onaylarını destekler ve isteğe bağlı olarak istemleri kaynak sohbette veya konuda yayımlayabilir. Onaylayıcılar sayısal Telegram kullanıcı kimlikleri olmalıdır.

• channels.telegram.execApprovals.enabled (en az bir onaylayıcı çözümlenebildiğinde "auto" etkinleştirir)
• 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 kimlerin konuşabileceğini ve normal yanıtları nereye gönderdiğini denetler; bir kişiyi exec onaylayıcısı yapmaz. Henüz komut sahibi yoksa onaylanan ilk DM eşleştirmesi commands.ownerAllowFrom için başlangıç yapılandırmasını oluşturur; böylece tek sahipli kurulumlar, execApprovals.approvers altında kimlikleri yinelemeden çalışır.

Kanal teslimatı komut metnini sohbette gösterir; channel veya both yalnızca güvenilir gruplarda/konularda etkinleştirilmelidir. İstem bir forum konusuna ulaştığında OpenClaw, onay istemi ve devamındaki iletiler için konuyu korur. Exec onaylarının süresi varsayılan olarak 30 dakika sonra dolar.

Satır içi onay düğmeleri ayrıca channels.telegram.capabilities.inlineButtons değerinin hedef yüzeye (dm, group veya all) izin vermesini gerektirir. plugin: ön ekli 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 -> Disable; ardından botu gruptan kaldırıp yeniden ekleyin.
• Yapılandırma, etiketleme içermeyen grup mesajlarını beklediğinde openclaw channels status uyarı verir.
• openclaw channels status --probe, açıkça belirtilen sayısal grup kimliklerini denetler; joker karakter "*" için üyelik sorgulanamaz.
• Hızlı oturum testi: /activation always.

• channels.telegram.groups mevcutsa grup listelenmelidir (veya "*" içermelidir).
• Botun gruba üye olduğunu doğrulayın.
• Atlama nedenleri için openclaw logs --follow değerini inceleyin.

• Gönderen kimliğinizi yetkilendirin (eşleştirme ve/veya sayısal allowFrom); grup ilkesi open olsa bile komut yetkilendirmesi geçerliliğini korur.
• BOT_COMMANDS_TOO_MUCH ile birlikte setMyCommands failed, yerel menüde çok fazla girdi olduğu anlamına gelir; Plugin/Skill/özel komutların sayısını azaltın veya yerel menüleri devre dışı bırakın.
• deleteMyCommands / setMyCommands başlangıç çağrıları ve sendChatAction yazma çağrıları sınırlıdır ve istek zaman aşımında Telegram'ın aktarım geri dönüşü üzerinden bir kez yeniden denenir. Sürekli ağ/fetch hataları genellikle api.telegram.org adresine DNS/HTTPS üzerinden erişilemediği anlamına gelir.

• getMe returned 401, yapılandırılan bot token'ı için bir Telegram kimlik doğrulama hatasıdır. BotFather'da token'ı yeniden kopyalayın veya oluşturun; ardından channels.telegram.botToken, tokenFile, accounts.<id>.botToken ya da TELEGRAM_BOT_TOKEN (varsayılan hesap) değerini güncelleyin.
• Başlangıç sırasındaki deleteWebhook 401 Unauthorized de bir kimlik doğrulama hatasıdır; bunu "Webhook yok" olarak değerlendirmek, aynı geçersiz token hatasını yalnızca daha sonraki bir API çağrısına erteler.

• Özel bir fetch/proxy ile Node 22+, AbortSignal türleri eşleşmezse anında iptal davranışını tetikleyebilir.
• Bazı ana makineler api.telegram.org adresini önce IPv6'ya çözümler; bozuk IPv6 çıkışı aralıklı API hatalarına neden olur.
• TypeError: fetch failed veya Network request for 'getUpdates' failed! içeren günlükler, kurtarılabilir ağ hataları olarak yeniden denenir.
• 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.
• deleteWebhook, yoklama başlangıcı sırasında geçici bir ağ hatasıyla başarısız olursa OpenClaw, yoklama öncesi başka bir denetim düzlemi çağrısı yapmak yerine uzun yoklamaya devam eder. Hâlâ etkin olan bir Webhook daha sonra getUpdates çakışması olarak ortaya çıkar; OpenClaw aktarımı yeniden oluşturur ve Webhook temizliğini yeniden dener.
• Günlüklerdeki Polling stall detected, varsayılan olarak tamamlanmış uzun yoklama canlılığı olmadan 120 saniye geçtikten sonra OpenClaw'ın yoklamayı yeniden başlatıp aktarımı yeniden oluşturduğu anlamına gelir.
• openclaw channels status --probe ve openclaw doctor; çalışan bir yoklama hesabı başlangıç ek süresinden sonra getUpdates işlemini tamamlamadığında, çalışan bir Webhook hesabı başlangıç ek süresinden sonra setWebhook işlemini tamamlamadığında veya son başarılı yoklama aktarımı etkinliği eski kaldığında uyarı verir.
• Telegram, Bot API aktarımı için işlem proxy ortam değişkenlerini dikkate alır: HTTP_PROXY, HTTPS_PROXY, ALL_PROXY ve küçük harfli çeşitleri. NO_PROXY / no_proxy yine de api.telegram.org değerini atlayabilir.
• Bir hizmet ortamı için OPENCLAW_PROXY_URL ayarlanmışsa ve standart proxy ortam değişkeni yoksa Telegram, Bot API aktarımı için de bu URL'yi kullanır.
• Doğrudan çıkış/TLS bağlantısı kararsız VPS ana makinelerinde Telegram API çağrılarını bir 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, sonrasında işlem varsayılanını (örneğin NODE_OPTIONS=--dns-result-order=ipv4first) dikkate alır; hiçbiri geçerli değilse Node 22+ üzerinde ipv4first değerine geri döner.
• WSL2'de veya yalnızca IPv4 davranışı daha iyi çalıştığında adres ailesi 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 sahte IP veya şeffaf proxy, medya indirmeleri sırasında api.telegram.org değerini başka bir özel/dâhilî/özel kullanım adresine dönüştürüyorsa yalnızca Telegram'a özgü atlamayı etkinleştirin:

channels:telegram:network:  dangerouslyAllowPrivateNetwork: true

• Aynı etkinleştirme seçeneği hesap başına channels.telegram.accounts.<accountId>.network.dangerouslyAllowPrivateNetwork konumunda kullanılabilir.
• Proxy'niz Telegram medya ana makinelerini 198.18.x.x aralığına çözümlüyorsa önce tehlikeli bayrağı kapalı bırakın; bu aralığa varsayılan olarak zaten izin verilir.

• Geçici ortam geçersiz kılmaları: 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