Telegram

Telegram botları varsayılan olarak Gizlilik Modu kullanır; bu, aldıkları grup mesajlarını sınırlar.

Botun tüm grup mesajlarını görmesi gerekiyorsa:

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

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

Yönetici durumu Telegram grup ayarlarından kontrol edilir.

Yönetici botlar tüm grup mesajlarını alır; bu, her zaman açık grup davranışı için yararlı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ışa verebilir:

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

Gereksinim:

• channels.telegram.streaming, off | partial | block | progress değerlerinden biridir (varsayılan: partial)
• progress araç ilerlemesi için düzenlenebilir tek bir durum taslağı tutar, tamamlandığında onu temizler ve son yanıtı normal mesaj olarak gönderir
• streaming.preview.toolProgress, araç/ilerleme güncellemelerinin aynı düzenlenen önizleme mesajını yeniden kullanıp kullanmayacağını denetler (önizleme akışı etkinken varsayılan: 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)
• eski channels.telegram.streamMode ve bool streaming değerleri algılanır; bunları channels.telegram.streaming.mode değerine geçirmek 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 veya yama özetleri. Telegram, v2026.4.22 ve sonrasındaki 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ı mesaja 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 sadece-son teslim istediğinizde kullanın: Telegram önizleme düzenlemeleri devre dışı bırakılır ve genel araç/ilerleme konuşmaları bağımsız durum mesajları olarak gönderilmek yerine bastırılır. Onay istemleri, medya yükleri ve hatalar yine normal son teslim üzerinden yönlendirilir. 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 çok Telegram iletisine bölünen uzun metin sonları mümkün olduğunda mevcut önizlemeyi ilk son parça olarak yeniden kullanır, ardından yalnızca kalan parçaları gönderir
• ilerleme modu sonları durum taslağını temizler ve taslağı yanıta düzenlemek yerine normal son teslimi kullanır
• tamamlanan metin doğrulanmadan önce son düzenleme başarısız olursa OpenClaw normal son teslimi kullanır ve bayat önizlemeyi temizler

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

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

Yalnızca Telegram akıl yürütme akışı:

• /reasoning stream üretim sırasında akıl yürütmeyi canlı önizlemeye gönderir
• akıl yürütme önizlemesi son teslimden sonra silinir; akıl yürütme görünür kalmalıysa /reasoning on kullanın
• son yanıt akıl yürütme metni olmadan gönderilir

Giden metin Telegram parse_mode: "HTML" kullanır.

• Markdown benzeri metin Telegram için güvenli HTML'ye işlenir.
• Ham model HTML'si, Telegram ayrıştırma hatalarını azaltmak için kaçışlanır.
• Telegram ayrıştırılmış HTML'yi reddederse OpenClaw düz metin olarak yeniden dener.

Bağlantı önizlemeleri varsayılan olarak etkindir ve channels.telegram.linkPreview: false ile devre dışı bırakılabilir.

Telegram komut menüsü kaydı başlangıçta setMyCommands ile işlenir.

Yerel komut varsayılanları:

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

Özel komut menüsü girdileri ekleyin:

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

Kurallar:

• adlar normalleştirilir (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ü girdileridir; davranışı otomatik olarak uygulamazlar
• Plugin/skill komutları Telegram menüsünde gösterilmese bile yazıldığında çalışmaya devam edebilir

Yerel komutlar devre dışı bırakılırsa yerleşikler kaldırılır. Özel/Plugin komutları yapılandırılmışsa yine kaydedilebilir.

Yaygın kurulum hataları:

• BOT_COMMANDS_TOO_MUCH ile setMyCommands failed, kırpmadan sonra Telegram menüsünün hâlâ 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 komutlarının 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 eklenmiş sondaki /bot<TOKEN> bölümünü kaldırır.
• getMe returned 401, Telegram'ın yapılandırılmış bot token'ını reddettiği anlamına gelir. botToken, tokenFile veya TELEGRAM_BOT_TOKEN değerini geçerli BotFather token'ı ile güncelleyin; OpenClaw yoklamadan önce durur, bu nedenle bu durum bir Webhook temizleme hatası olarak bildirilmez.
• Ağ/fetch hatalarıyla setMyCommands failed genellikle api.telegram.org adresine giden DNS/HTTPS erişiminin engellendiği anlamına gelir.

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

device-pair Plugin 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 güncel istek için /pair approve latest

Kurulum kodu kısa ömürlü bir önyükleme token'ı taşır. Yerleşik önyükleme devri, birincil node token'ını scopes: [] değerinde tutar; devredilen herhangi bir operatör token'ı operator.approvals, operator.read, operator.talk.secrets ve operator.write ile sınırlı kalır. Önyükleme kapsam kontrolleri rol öneklidir, bu nedenle bu operatör izin listesi yalnızca operatör isteklerini karşılar; operatör olmayan rollerin yine kendi rol önekleri altında kapsamlara ihtiyacı vardır.

Bir cihaz değişen kimlik doğrulama ayrıntılarıyla (örneğin rol/kapsamlar/açık anahtar) yeniden denerse ö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.

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

Geri çağırma tıklamaları aracıya 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)
• createForumTopic (chatId, name, isteğe bağlı iconColor, iconCustomEmojiId)

Kanal ileti eylemleri ergonomik takma adları açığa çıkarır (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şlangıç/yeniden yükleme) kullanır, bu nedenle eylem yolları gönderim başına geçici SecretRef yeniden çözümlemesi yapmaz.

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

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

• [[reply_to_current]] tetikleyen iletiye yanıt verir
• [[reply_to:<id>]] belirli bir Telegram ileti 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ı özeti ekler. Telegram yerel alıntı metnini 1024 UTF-16 kod birimiyle sınırlar; bu nedenle daha uzun iletiler 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 dikkate alınır.

Forum süper grupları:

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

Genel konu (threadId=1) özel durumu:

• ileti gönderimleri message_thread_id değerini atlar (Telegram sendMessage(...thread_id=1) çağrısını reddeder)
• yazıyor eylemleri yine 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 özgüdür ve grup varsayılanlarından devralınmaz.

Konu başına aracı yönlendirme: Her konu, konu yapılandırmasında agentId ayarlanarak farklı bir aracıya 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
          }
        }
      }
    }
  }
}

Her konu daha sonra kendi oturum anahtarına sahip olur: agent:zu:telegram:group:-1001234567890:topic:3

Kalıcı ACP konu bağlaması: Forum konuları, üst düzey tipli ACP bağlamaları üzerinden ACP harness oturumlarını sabitleyebilir (type: "acp" ve match.channel: "telegram", peer.kind: "group" içeren bindings[] ve -1001234567890:topic:42 gibi konu nitelikli bir kimlik). Şu anda gruplardaki/süper gruplardaki forum konularıyla sınırlıdır. Bkz. ACP Aracı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; takip iletileri 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 açığa çıkarır. message_thread_id içeren DM sohbetleri, varsayılan olarak düz oturumlarda DM yönlendirmesini ve yanıt meta verilerini korur; konu duyarlı oturum anahtarlarını yalnızca threadReplies: "inbound", threadReplies: "always", requireTopic: true veya eşleşen bir konu yapılandırmasıyla ayarlandığında kullanırlar. Hesap varsayılanı için üst düzey channels.telegram.dm.threadReplies değerini, tek bir DM için direct.<chatId>.threadReplies değerini kullanın.

# Ses mesajları

Telegram, sesli notlar ile ses dosyalarını ayırt eder.

• varsayılan: ses dosyası davranışı
• sesli not göndermeyi zorlamak için aracı yanıtında [[audio_as_voice]] etiketi
• gelen sesli not transkriptleri, aracı bağlamında makine tarafından üretilmiş, güvenilmeyen metin olarak çerçevelenir; bahsetme algılama yine de ham transkripti kullanır, böylece bahsetme kapılı 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ı açıklama metinlerini 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 önbellek dosyası:

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

Çıkartmalar bir kez açıklanır (mümkün olduğunda) ve tekrarlanan görüntü çağrılarını azaltmak için önbelleğe alınır.

Çıkartma eylemlerini etkinleştirme:

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

Çıkartma gönderme eylemi:

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

Önbelleğe alınmış çıkartmalarda arama:

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

Telegram tepkileri message_reaction güncellemeleri olarak gelir (mesaj yüklerinden ayrıdır).

Etkinleştirildiğinde OpenClaw şuna benzer sistem olaylarını kuyruğa alır:

• Telegram tepkisi eklendi: 👍, Alice (@alice) tarafından msg 42 üzerinde

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 kullanıcı tepkileri anlamına gelir (gönderilen mesaj önbelleği üzerinden en iyi çaba).
• Tepki olayları yine de Telegram erişim denetimlerine (dmPolicy, allowFrom, groupPolicy, groupAllowFrom) uyar; yetkisiz göndericiler düşürülür.
• Telegram tepki güncellemelerinde iş parçacığı kimlikleri sağlamaz.
  • forum olmayan gruplar, grup sohbeti oturumuna yönlendirilir
  • forum grupları, tam kaynak konuya değil grup 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.

Çözüm sırası:

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

Notlar:

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

Kanal yapılandırması 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 tamamlanmış olarak yazılmaz.

Yerel dinleyici 127.0.0.1:8787 adresine bağlanır. Genel giriş için yerel bağlantı noktasının önüne bir ters proxy koyun veya 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 yoklamada kullanılan aynı sohbet başına/konu başına bot şeritleri üzerinden eşzamansız olarak işler; bu nedenle yavaş aracı dönüşleri Telegram'ın teslim ACK değerini tutmaz.

• 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 dağıtılmadan önce ne kadar süre arabelleğe alınacağını denetler. 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ılmış değerleri 60 saniyelik giden metin/yazıyor isteği korumasının altında sınırlar; böylece grammY, OpenClaw'ın taşıma koruması ve yedeği çalışmadan önce görünür yanıt teslimini iptal etmez. Uzun yoklama yine de 45 saniyelik getUpdates isteği koruması kullanır, böylece boşta bekleyen yoklamalar süresiz olarak terk edilmez.
• channels.telegram.pollingStallThresholdMs varsayılanı 120000 değeridir; 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 kullanır (varsayılan 50); 0 devre dışı bırakır.
• yanıt/alıntı/iletme ek bağlamı şu anda alındığı gibi geçirilir.
• Telegram izin listeleri, tam bir ek bağlam redaksiyon sınırı değil, öncelikle aracıyı kimin tetikleyebileceğini kapılar.
• 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 ön bağlantı hataları için sınırlı bir 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 konu 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 bu sohbette sabitleyebiliyorsa sabitlenmiş teslim istemek için --pin veya --delivery '{"pin":true}'
• giden görselleri ve GIF’leri sıkıştırılmış fotoğraf veya animasyonlu medya yüklemeleri yerine belge olarak göndermek için --force-document

Eylem kapılama:

• 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ırakarak Telegram yoklama oluşturmayı devre dışı bırakır

Telegram, onaylayıcı DM’lerinde exec onaylarını destekler ve isteğe bağlı olarak kaynak sohbete veya konuya istemler 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 denetler. Bunlar bir kişiyi exec onaylayıcısı yapmaz. Henüz komut sahibi yokken ilk onaylanmış DM eşleştirmesi commands.ownerAllowFrom değerini 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 değerlerini yalnızca güvenilir gruplarda/konularda etkinleştirin. İstem bir forum konusuna düştüğünde OpenClaw, onay istemi ve takip 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 değerinin hedef yüzeye (dm, group veya all) izin vermesini gerektirir. plugin: öneki olan 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 kaldırıp yeniden ekleyin
• Yapılandırma bahsedilmemiş grup mesajları beklediğinde openclaw channels status uyarır.
• openclaw channels status --probe açık sayısal grup kimliklerini denetleyebilir; "*" joker karakteri üyelik açısından denetlenemez.
• hızlı oturum testi: /activation always.

• channels.telegram.groups varsa grup listelenmiş olmalıdır (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şleme ve/veya sayısal allowFrom)
• grup ilkesi open olsa bile komut yetkilendirmesi yine 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
• başlangıçtaki deleteMyCommands / setMyCommands çağrıları ve sendChatAction yazıyor çağrıları sınırlandırılmıştır ve istek zaman aşımında Telegram'ın taşıma yedeği üzerinden bir kez yeniden denenir. Kalıcı ağ/getirme hataları genellikle api.telegram.org için DNS/HTTPS erişilebilirlik sorunlarını gösterir

• getMe returned 401, yapılandırılmış bot token için bir Telegram kimlik doğrulama hatasıdır.
• BotFather içinde 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 değerini 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 hatasını 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 olarak çö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, çalıştırıcının ilk getUpdates öncesinde ikinci bir getMe yapmasına gerek kalmaması için başarılı başlangıç getMe denetimini grammY için yeniden kullanır.
• 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. Hala etkin olan bir Webhook, getUpdates çakışması olarak görünür; OpenClaw ardından Telegram taşımasını yeniden oluşturur ve Webhook temizliğini yeniden dener.
• Telegram soketleri kısa ve sabit bir düzende yenileniyorsa düşük bir channels.telegram.timeoutSeconds değeri olup olmadığını kontrol edin; bot istemcileri, yapılandırılmış değerleri giden ve getUpdates istek korumalarının altındaysa sınırlar, ancak eski sürümler bu değerler bu 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 120 saniye geçtikten 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ıç bekleme süresinden sonra getUpdates tamamlamadığında, çalışan bir Webhook hesabı başlangıç bekleme süresinden 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ıysa ancak ana makineniz yine de hatalı 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, 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 de 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 bu URL'yi Bot API taşıması için de 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, sonra channels.telegram.network.dnsResultOrder, sonra 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 karşılaştırma 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 adresini başka bir özel/dahili/özel kullanım adresine yeniden yazıyorsa, yalnızca Telegram için geçerli atlamaya katılabilirsiniz:

channels:
telegram:
network:
  dangerouslyAllowPrivateNetwork: true

• Aynı katılım hesap başına channels.telegram.accounts.<accountId>.network.dangerouslyAllowPrivateNetwork konumunda kullanılabilir.
• Proxy'niz Telegram medya ana makinelerini 198.18.x.x içine çözümlüyorsa önce tehlikeli bayrağı kapalı bırakın. Telegram medyası RFC 2544 karşılaştırma 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 A
dig +short api.telegram.org AAAA