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

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

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

• channels.telegram.streaming değeri off | partial | block | progress olmalıdır (varsayılan: partial)
• progress, Telegram’da partial olarak eşlenir (kanallar arası adlandırma uyumluluğu)
• eski channels.telegram.streamMode ve boolean streaming değerleri otomatik olarak eşlenir

• DM: OpenClaw aynı önizleme mesajını korur ve yerinde son düzenlemeyi yapar (ikinci mesaj yok)
• grup/konu: OpenClaw aynı önizleme mesajını korur ve yerinde son düzenlemeyi yapar (ikinci mesaj yok)

• /reasoning stream, oluşturma sırasında akıl yürütmeyi canlı önizlemeye gönderir
• son yanıt akıl yürütme metni olmadan gönderilir

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

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

{
  channels: {
    telegram: {
      customCommands: [
        { command: "backup", description: "Git yedeği" },
        { command: "generate", description: "Bir görsel oluştur" },
      ],
    },
  },
}

• 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ın üzerine yazamaz
• çakışmalar/tekrarlar 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ığında yine çalışabilir

• BOT_COMMANDS_TOO_MUCH ile setMyCommands failed, Telegram menüsünün kırpmadan sonra hâlâ taştığı anlamına gelir; plugin/skill/özel komutları azaltın veya channels.telegram.commands.native değerini devre dışı bırakın.
• ağ/fetch hatalarıyla setMyCommands failed, genellikle api.telegram.org adresine giden DNS/HTTPS çıkışının engellendiği anlamına gelir.

​

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

1. /pair kurulum kodu oluşturur
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 son istek için /pair approve latest

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

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

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

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

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

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

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

• off (varsayılan)
• first
• all

• konu oturum anahtarlarına :topic:<threadId> eklenir
• yanıtlar ve yazıyor durumu konu iş parçacığını hedefler
• konu config yolu: channels.telegram.groups.<chatId>.topics.<threadId>

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

{
  channels: {
    telegram: {
      groups: {
        "-1001234567890": {
          topics: {
            "1": { agentId: "main" },      // Genel konu → main ajanı
            "3": { agentId: "zu" },        // Geliştirme konusu → zu ajanı
            "5": { agentId: "coder" }      // Kod inceleme → coder ajanı
          }
        }
      }
    }
  }
}

• type: "acp" ve match.channel: "telegram" içeren bindings[]

{
  agents: {
    list: [
      {
        id: "codex",
        runtime: {
          type: "acp",
          acp: {
            agent: "codex",
            backend: "acpx",
            mode: "persistent",
            cwd: "/workspace/openclaw",
          },
        },
      },
    ],
  },
  bindings: [
    {
      type: "acp",
      agentId: "codex",
      match: {
        channel: "telegram",
        accountId: "default",
        peer: { kind: "group", id: "-1001234567890:topic:42" },
      },
    },
  ],
  channels: {
    telegram: {
      groups: {
        "-1001234567890": {
          topics: {
            "42": {
              requireMention: false,
            },
          },
        },
      },
    },
  },
}

• /acp spawn <agent> --thread here|auto, mevcut Telegram konusunu yeni bir ACP oturumuna bağlayabilir.
• Sonraki konu mesajları doğrudan bağlı ACP oturumuna yönlendirilir (/acp steer gerekmez).
• OpenClaw, başarılı bir bağlamadan sonra oluşturma onay mesajını konu içinde sabitler.
• channels.telegram.threadBindings.spawnAcpSessions=true gerektirir.

• MessageThreadId
• IsForum

• message_thread_id içeren özel sohbetler DM yönlendirmesini korur ancak iş parçacığı farkındalıklı oturum anahtarları/yanıt hedefleri kullanır.

​

Sesli mesajlar

• varsayılan: ses dosyası davranışı
• ajan yanıtına [[audio_as_voice]] etiketi eklenirse sesli not olarak gönderimi zorlar

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

​

Video mesajları

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

​

Sticker’lar

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

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

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

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

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

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

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

• 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önderilmiş mesajlara kullanıcı tepkileri anlamına gelir (gönderilmiş mesaj önbelleği aracılığıyla en iyi çabayla).
• Tepki olayları yine Telegram erişim denetimlerine (dmPolicy, allowFrom, groupPolicy, groupAllowFrom) uyar; yetkisiz gönderenler 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, grubun genel konu oturumuna (:topic:1) yönlendirilir

• channels.telegram.accounts.<accountId>.ackReaction
• channels.telegram.ackReaction
• messages.ackReaction
• ajan kimliği emoji geri dönüşü (agents.list[].identity.emoji, aksi halde ”👀”)

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

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

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

• channels.telegram.webhookUrl ayarlayın
• channels.telegram.webhookSecret ayarlayın (webhookUrl ayarlandığında gereklidir)
• isteğe bağlı channels.telegram.webhookPath (varsayılan /telegram-webhook)
• isteğe bağlı channels.telegram.webhookHost (varsayılan 127.0.0.1)
• isteğe bağlı channels.telegram.webhookPort (varsayılan 8787)

• 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.timeoutSeconds, Telegram API istemci zaman aşımını geçersiz kılar (ayarlanmazsa grammY varsayılanı uygulanır).
• 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ı/yönlendirme ek bağlamı şu anda alındığı gibi geçirilir.
• Telegram allowlist’leri öncelikle tam bir ek bağlam sansürleme sınırı değil, ajanın kim tarafından tetiklenebileceğini geçitler.
• DM geçmişi denetimleri:
  • channels.telegram.dmHistoryLimit
  • channels.telegram.dms["<user_id>"].historyLimit
• channels.telegram.retry config’i, kurtarılabilir giden API hataları için Telegram gönderim yardımcılarına (CLI/tools/actions) uygulanır.

openclaw message send --channel telegram --target 123456789 --message "hi"
openclaw message send --channel telegram --target @name --message "hi"

openclaw message poll --channel telegram --target 123456789 \
  --poll-question "Ship it?" --poll-option "Yes" --poll-option "No"
openclaw message poll --channel telegram --target -1001234567890:topic:42 \
  --poll-question "Pick a time" --poll-option "10am" --poll-option "2pm" \
  --poll-duration-seconds 300 --poll-public

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

• channels.telegram.capabilities.inlineButtons izin verdiğinde satır içi klavyeler için --buttons
• 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

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

• channels.telegram.execApprovals.enabled
• channels.telegram.execApprovals.approvers (isteğe bağlıdır; mümkün olduğunda allowFrom ve doğrudan defaultTo değerlerinden çıkarılan sayısal sahip kimliklerine geri döner)
• channels.telegram.execApprovals.target (dm | channel | both, varsayılan: dm)
• agentFilter, sessionFilter

• target: "dm", onay istemlerini yalnızca çözümlenen onaylayıcı DM’lerine gönderir
• target: "channel", istemi kaynak Telegram sohbetine/konusuna geri gönderir
• target: "both", istemleri onaylayıcı DM’lerine ve kaynak sohbet/konuya gönderir

• plugin: öneki taşıyan kimlikler her zaman plugin onayları üzerinden çözümlenir.
• Diğer onay kimlikleri önce exec.approval.resolve dener.
• Telegram aynı zamanda plugin onayları için yetkiliyse ve gateway exec onayının bilinmediğini/süresinin dolduğunu söylerse, Telegram bir kez plugin.approval.resolve üzerinden yeniden dener.
• Gerçek exec onay reddi/hataları sessizce plugin onay çözümlemesine düşmez.

• 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
• openclaw channels status, config bahsedilmeyen grup mesajları beklediğinde uyarı verir.
• openclaw channels status --probe, açık sayısal grup kimliklerini denetleyebilir; joker "*" için üyelik denetimi yapılamaz.
• hızlı oturum testi: /activation always.

• channels.telegram.groups varsa grup listelenmiş olmalıdır (veya "*" içermelidir)
• botun gruba üyeliğini doğrulayın
• atlama nedenleri için günlükleri gözden geçirin: openclaw logs --follow

• gönderen kimliğinizi yetkilendirin (eşleştirme ve/veya sayısal allowFrom)
• grup ilkesi open olsa bile komut yetkilendirmesi yine geçerlidir
• 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
• ağ/fetch hatalarıyla setMyCommands failed, genellikle api.telegram.org adresine DNS/HTTPS erişilebilirliği sorunlarını gösterir

• Node 22+ + özel fetch/proxy, AbortSignal türleri uyuşmazsa anında iptal davranışını tetikleyebilir.
• Bazı ana bilgisayarlar api.telegram.org adresini önce IPv6’ya çözümler; bozuk IPv6 çıkışı aralıklı Telegram API hatalarına yol açabilir.
• Günlüklerde TypeError: fetch failed veya Network request for 'getUpdates' failed! varsa, OpenClaw artık bunları kurtarılabilir ağ hataları olarak yeniden dener.
• Doğrudan çıkışı/TLS’si kararsız VPS ana bilgisayarlarında, 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 (WSL2 hariç) ve dnsResultOrder=ipv4first kullanır.
• Ana bilgisayarınız 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 benchmark aralığı yanıtlarına (198.18.0.0/15) Telegram medya indirmeleri için zaten varsayılan olarak 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, Telegram’a özel bu baypası etkinleştirebilirsiniz:

channels:
  telegram:
    network:
      dangerouslyAllowPrivateNetwork: true

• Aynı isteğe bağlı etkinleştirme hesap başına da channels.telegram.accounts.<accountId>.network.dangerouslyAllowPrivateNetwork üzerinden kullanılabilir.
• Proxy’niz Telegram medya ana bilgisayarlarını 198.18.x.x içine çözümlüyorsa, önce tehlikeli bayrağı kapalı bırakın. Telegram medyası zaten RFC 2544 benchmark aralığına varsayılan olarak izin verir.

• Ortam değişkeni 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