Telegram

• /setprivacy로 개인정보 보호 모드를 비활성화하거나
• bot을 그룹 관리자로 지정합니다.

• 그룹 추가를 허용/거부하려면 /setjoingroups
• 그룹 표시 동작을 설정하려면 /setprivacy

• direct chat: preview 메시지 + editMessageText
• group/topic: preview 메시지 + editMessageText

• channels.telegram.streaming은 off | partial | block | progress입니다(기본값: partial)
• 짧은 초기 answer preview는 debounce된 뒤, run이 아직 활성 상태이면 제한된 지연 후 materialize됩니다
• progress는 tool 진행 상황을 위한 편집 가능한 status draft 하나를 유지하고, tool 진행 상황보다 answer activity가 먼저 도착하면 안정적인 status label을 표시하며, 완료 시 이를 지우고 최종 answer를 일반 메시지로 보냅니다
• streaming.preview.toolProgress는 tool/progress 업데이트가 같은 편집된 preview 메시지를 재사용할지 제어합니다(기본값: preview streaming이 활성화되어 있으면 true)
• streaming.preview.commandText는 해당 tool-progress 줄 안의 command/exec 세부 정보를 제어합니다. raw(기본값, 릴리스된 동작 보존) 또는 status(tool label만)
• streaming.progress.commentary(기본값: false)는 임시 progress draft에 assistant commentary/preamble 텍스트를 포함하도록 opt in합니다
• legacy channels.telegram.streamMode, boolean streaming 값, retired native draft preview 키는 감지됩니다. 현재 streaming config로 마이그레이션하려면 openclaw doctor --fix를 실행하세요

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

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

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

• 짧은 DM/group/topic preview: OpenClaw는 같은 preview 메시지를 유지하고 최종 edit를 제자리에서 수행합니다
• 여러 Telegram 메시지로 분할되는 긴 텍스트 final은 가능하면 기존 preview를 첫 번째 final chunk로 재사용한 뒤, 나머지 chunk만 보냅니다
• progress-mode final은 status draft를 지우고 draft를 answer로 편집하는 대신 일반 final delivery를 사용합니다
• 완료된 텍스트가 확인되기 전에 최종 edit가 실패하면 OpenClaw는 일반 final delivery를 사용하고 오래된 preview를 정리합니다

• /reasoning stream은 지원되는 채널의 reasoning-preview 경로를 사용합니다. Telegram에서는 생성 중 reasoning을 live preview로 스트리밍합니다
• reasoning preview는 final delivery 후 삭제됩니다. reasoning이 계속 표시되어야 하면 /reasoning on을 사용하세요
• 최종 answer는 reasoning 텍스트 없이 전송됩니다

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

• agent는 이 bot/account에서 Telegram rich message를 사용할 수 있다고 안내받습니다.
• Markdown 텍스트는 OpenClaw의 Markdown IR을 통해 렌더링되고 Telegram rich HTML로 전송됩니다.
• 명시적 rich HTML payload는 heading, table, detail, rich media, formula 같은 지원되는 Bot API 10.1 tag를 보존합니다.
• rich message가 caption을 대체하지 않으므로 media caption은 계속 Telegram HTML caption을 사용합니다.

• commands.native: "auto"는 Telegram에 대해 native command를 활성화합니다

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

• name은 정규화됩니다(선행 / 제거, 소문자)
• 유효한 pattern: a-z, 0-9, _, 길이 1..32
• custom command는 native command를 override할 수 없습니다
• conflict/duplicate는 건너뛰고 log됩니다

• custom command는 menu entry일 뿐이며, 동작을 자동으로 구현하지 않습니다
• Plugin/Skills command는 Telegram menu에 표시되지 않아도 입력하면 계속 작동할 수 있습니다

• BOT_COMMANDS_TOO_MUCH와 함께 setMyCommands failed가 표시되면 trimming 후에도 Telegram menu가 여전히 overflow되었다는 뜻입니다. Plugin/Skills/custom command를 줄이거나 channels.telegram.commands.native를 비활성화하세요.
• direct Bot API curl command는 작동하는데 deleteWebhook, deleteMyCommands, 또는 setMyCommands가 404: Not Found로 실패한다면 channels.telegram.apiRoot가 전체 /bot<TOKEN> endpoint로 설정되었을 수 있습니다. apiRoot는 Bot API root만이어야 하며, openclaw doctor --fix는 실수로 붙은 trailing /bot<TOKEN>을 제거합니다.
• getMe returned 401은 Telegram이 구성된 봇 토큰을 거부했다는 뜻입니다. botToken, tokenFile, 또는 TELEGRAM_BOT_TOKEN을 현재 BotFather 토큰으로 업데이트하세요. OpenClaw는 polling 전에 중지하므로 이는 webhook cleanup 실패로 보고되지 않습니다.
• network/fetch error와 함께 setMyCommands failed가 표시되면 보통 api.telegram.org로 나가는 DNS/HTTPS가 차단되었다는 뜻입니다.

​

Device pairing command(device-pair Plugin)

1. /pair는 setup code를 생성합니다
2. iOS app에 code를 붙여넣습니다
3. /pair pending은 pending request를 나열합니다(role/scope 포함)
4. request를 승인합니다.
   • 명시적 승인은 /pair approve <requestId>
   • pending request가 하나뿐이면 /pair approve
   • 가장 최근 항목은 /pair approve latest

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

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

• off
• dm
• group
• all
• allowlist (기본값)

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

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

• sendMessage (to, content, 선택 사항 mediaUrl, replyToMessageId, messageThreadId)
• react (chatId, messageId, emoji)
• deleteMessage (chatId, messageId)
• editMessage (chatId, messageId, content 또는 caption, 선택 사항 presentation 인라인 버튼; 버튼만 수정하는 경우 reply markup을 업데이트함)
• createForumTopic (chatId, name, 선택 사항 iconColor, iconCustomEmojiId)

• channels.telegram.actions.sendMessage
• channels.telegram.actions.deleteMessage
• channels.telegram.actions.reactions
• channels.telegram.actions.sticker (기본값: 비활성화)

• [[reply_to_current]]는 트리거한 메시지에 답장합니다
• [[reply_to:<id>]]는 특정 Telegram 메시지 ID에 답장합니다

• off (기본값)
• first
• all

• 토픽 세션 키는 :topic:<threadId>를 추가합니다
• 답장과 입력 상태는 토픽 스레드를 대상으로 합니다
• 토픽 구성 경로: channels.telegram.groups.<chatId>.topics.<threadId>

• 메시지 전송은 message_thread_id를 생략합니다(Telegram은 sendMessage(...thread_id=1)을 거부함)
• 입력 작업은 여전히 message_thread_id를 포함합니다

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

​

오디오 메시지

• 기본값: 오디오 파일 동작
• 에이전트 답장에 [[audio_as_voice]] 태그를 넣으면 음성 메모 전송을 강제합니다
• 인바운드 음성 메모 전사는 에이전트 컨텍스트에서 기계 생성, 신뢰할 수 없는 텍스트로 프레이밍됩니다. 멘션 감지는 여전히 원시 전사를 사용하므로 멘션 게이트가 적용된 음성 메시지가 계속 작동합니다.

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

​

비디오 메시지

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

​

스티커

• 정적 WEBP: 다운로드되어 처리됨(플레이스홀더 <media:sticker>)
• 애니메이션 TGS: 건너뜀
• 비디오 WEBM: 건너뜀

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

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

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

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

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

• channels.telegram.reactionNotifications: off | own | all(기본값: own)
• channels.telegram.reactionLevel: off | ack | minimal | extensive(기본값: minimal)

• own은 봇이 보낸 메시지에 대한 사용자 반응만을 의미합니다(전송 메시지 캐시를 통한 최선의 처리).
• 반응 이벤트도 Telegram 접근 제어(dmPolicy, allowFrom, groupPolicy, groupAllowFrom)를 따르며, 권한이 없는 발신자는 삭제됩니다.
• Telegram은 반응 업데이트에서 스레드 ID를 제공하지 않습니다.
  • 포럼이 아닌 그룹은 그룹 채팅 세션으로 라우팅됩니다.
  • 포럼 그룹은 정확한 원래 토픽이 아니라 그룹 일반 토픽 세션(:topic:1)으로 라우팅됩니다.

• channels.telegram.accounts.<accountId>.ackReaction
• channels.telegram.ackReaction
• messages.ackReaction
• 에이전트 ID 이모지 폴백(agents.list[].identity.emoji, 없으면 ”👀”)

• Telegram은 유니코드 이모지를 예상합니다(예: ”👀”).
• 채널 또는 계정의 반응을 비활성화하려면 ""를 사용하세요.

• channels.telegram.groups를 업데이트하기 위한 그룹 마이그레이션 이벤트(migrate_to_chat_id)
• /config set 및 /config unset(명령 활성화 필요)

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

• channels.telegram.textChunkLimit의 기본값은 4000입니다.
• channels.telegram.chunkMode="newline"은 길이로 분할하기 전에 문단 경계(빈 줄)를 우선합니다.
• channels.telegram.mediaMaxMb(기본값 100)는 수신 및 발신 Telegram 미디어 크기를 제한합니다.
• channels.telegram.mediaGroupFlushMs(기본값 500)는 Telegram 앨범/미디어 그룹을 OpenClaw가 하나의 수신 메시지로 전달하기 전에 얼마나 오래 버퍼링할지 제어합니다. 앨범 일부가 늦게 도착하면 늘리고, 앨범 응답 지연을 줄이려면 줄이세요.
• channels.telegram.timeoutSeconds는 Telegram API 클라이언트 타임아웃을 재정의합니다(설정하지 않으면 grammY 기본값이 적용됨). Bot 클라이언트는 설정값을 60초 발신 텍스트/입력 중 요청 가드보다 낮게 제한하여, OpenClaw의 전송 가드와 fallback이 실행되기 전에 grammY가 표시되는 응답 전달을 중단하지 않도록 합니다. Long polling은 여전히 45초 getUpdates 요청 가드를 사용하므로 유휴 poll이 무기한 방치되지 않습니다.
• channels.telegram.pollingStallThresholdMs의 기본값은 120000입니다. polling 중단 재시작이 오탐일 때만 30000에서 600000 사이로 조정하세요.
• 그룹 컨텍스트 기록은 channels.telegram.historyLimit 또는 messages.groupChat.historyLimit(기본값 50)을 사용합니다. 0이면 비활성화됩니다.
• 응답/인용/전달 보조 컨텍스트는 Gateway가 상위 메시지를 관찰한 경우 선택된 하나의 대화 컨텍스트 창으로 정규화됩니다. 관찰된 메시지 캐시는 OpenClaw SQLite Plugin 상태에 저장되며, openclaw doctor --fix는 레거시 sidecar를 가져옵니다. Telegram은 업데이트에 얕은 reply_to_message 하나만 포함하므로, 캐시보다 오래된 체인은 Telegram의 현재 업데이트 payload로 제한됩니다.
• Telegram allowlist는 주로 누가 agent를 트리거할 수 있는지를 제어하며, 완전한 보조 컨텍스트 비식별화 경계가 아닙니다.
• DM 기록 제어:
  • channels.telegram.dmHistoryLimit
  • channels.telegram.dms["<user_id>"].historyLimit
• channels.telegram.retry 설정은 복구 가능한 발신 API 오류에 대해 Telegram 전송 helper(CLI/tools/actions)에 적용됩니다. 수신 최종 응답 전달도 Telegram 사전 연결 실패에 대해 제한된 safe-send 재시도를 사용하지만, 표시되는 메시지를 중복할 수 있는 모호한 전송 후 네트워크 envelope은 재시도하지 않습니다.

openclaw message send --channel telegram --target 123456789 --message "hi"
openclaw message send --channel telegram --target @name --message "hi"
openclaw message send --channel telegram --target -1001234567890:topic:42 --message "hi topic"

openclaw message poll --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 topic용 --thread-id(또는 :topic: 대상 사용)

• channels.telegram.capabilities.inlineButtons가 허용하는 경우 inline keyboard용 buttons 블록과 함께 --presentation
• bot이 해당 chat에서 pin할 수 있을 때 pin된 전달을 요청하는 --pin 또는 --delivery '{"pin":true}'
• 발신 이미지, GIF, 동영상을 압축된 사진, animated-media 또는 동영상 업로드 대신 문서로 보내는 --force-document

• channels.telegram.actions.sendMessage=false는 poll을 포함한 발신 Telegram 메시지를 비활성화합니다.
• channels.telegram.actions.poll=false는 일반 전송은 활성화한 채 Telegram poll 생성을 비활성화합니다.

• channels.telegram.execApprovals.enabled(해결 가능한 승인자가 하나 이상 있으면 자동 활성화)
• channels.telegram.execApprovals.approvers(commands.ownerAllowFrom의 숫자 owner ID로 fallback)
• channels.telegram.execApprovals.target: dm(기본값) | channel | both
• agentFilter, sessionFilter

• requireMention=false이면 Telegram privacy mode가 전체 가시성을 허용해야 합니다.
  • BotFather: /setprivacy -> Disable
  • 그런 다음 bot을 그룹에서 제거하고 다시 추가
• 설정이 mention 없는 그룹 메시지를 기대하면 openclaw channels status가 경고합니다.
• openclaw channels status --probe는 명시적인 숫자 group ID를 확인할 수 있습니다. wildcard "*"는 멤버십 probe를 할 수 없습니다.
• 빠른 세션 테스트: /activation always.

• channels.telegram.groups가 있으면 그룹이 목록에 있어야 합니다(또는 "*" 포함).
• 그룹 내 bot 멤버십 확인
• skip 이유는 로그 확인: openclaw logs --follow

• 발신자 identity를 승인하세요(pairing 및/또는 숫자 allowFrom).
• 그룹 정책이 open이어도 command 승인은 계속 적용됩니다.
• BOT_COMMANDS_TOO_MUCH와 함께 setMyCommands failed가 표시되면 native menu 항목이 너무 많다는 뜻입니다. Plugin/skill/custom command를 줄이거나 native menu를 비활성화하세요.
• deleteMyCommands / setMyCommands 시작 호출과 sendChatAction 입력 호출은 제한되어 있으며 요청 timeout 시 Telegram의 transport fallback을 통해 한 번 재시도합니다. 지속적인 network/fetch 오류는 일반적으로 api.telegram.org에 대한 DNS/HTTPS 도달성 문제를 나타냅니다.

• getMe returned 401은 설정된 bot token에 대한 Telegram 인증 실패입니다.
• BotFather에서 bot token을 다시 복사하거나 재생성한 다음, 기본 계정의 channels.telegram.botToken, channels.telegram.tokenFile, channels.telegram.accounts.<id>.botToken 또는 TELEGRAM_BOT_TOKEN을 업데이트하세요.
• 시작 중 deleteWebhook 401 Unauthorized도 auth 실패입니다. 이를 “webhook이 없음”으로 처리하면 동일한 잘못된 token 실패를 이후 API 호출로 미룰 뿐입니다.

• Node 22+와 custom fetch/proxy는 AbortSignal type이 일치하지 않으면 즉시 abort 동작을 유발할 수 있습니다.
• 일부 host는 api.telegram.org를 IPv6로 먼저 해석합니다. 손상된 IPv6 egress는 간헐적인 Telegram API 실패를 일으킬 수 있습니다.
• 로그에 TypeError: fetch failed 또는 Network request for 'getUpdates' failed!가 포함되면 OpenClaw는 이제 이를 복구 가능한 네트워크 오류로 재시도합니다.
• polling 시작 중 OpenClaw는 grammY를 위해 성공한 시작 getMe probe를 재사용하므로 runner가 첫 getUpdates 전에 두 번째 getMe를 수행할 필요가 없습니다.
• polling 시작 중 deleteWebhook이 일시적인 네트워크 오류로 실패하면 OpenClaw는 또 다른 pre-poll control-plane 호출을 하지 않고 long polling으로 계속 진행합니다. 아직 활성화된 webhook은 getUpdates conflict로 드러납니다. 그러면 OpenClaw는 Telegram transport를 다시 만들고 webhook cleanup을 재시도합니다.
• Telegram socket이 짧고 고정된 주기로 재활용되면 낮은 channels.telegram.timeoutSeconds를 확인하세요. bot 클라이언트는 설정값을 발신 및 getUpdates 요청 가드보다 낮게 제한하지만, 이전 release에서는 이 값이 해당 가드보다 낮게 설정되면 모든 poll 또는 응답이 abort될 수 있었습니다.
• 로그에 Polling stall detected가 포함되면 OpenClaw는 기본적으로 완료된 long-poll liveness 없이 120초가 지난 뒤 polling을 다시 시작하고 Telegram transport를 다시 만듭니다.
• openclaw channels status --probe 및 openclaw doctor는 실행 중인 polling 계정이 시작 grace 이후 getUpdates를 완료하지 않았거나, 실행 중인 webhook 계정이 시작 grace 이후 setWebhook을 완료하지 않았거나, 마지막으로 성공한 polling transport activity가 오래되었을 때 경고합니다.
• 장시간 실행되는 getUpdates 호출은 정상인데 host가 계속 polling-stall 재시작을 오탐으로 보고할 때만 channels.telegram.pollingStallThresholdMs를 늘리세요. 지속적인 중단은 일반적으로 host와 api.telegram.org 사이의 proxy, DNS, IPv6 또는 TLS egress 문제를 가리킵니다.
• Telegram은 Bot API transport에 대해 HTTP_PROXY, HTTPS_PROXY, ALL_PROXY 및 해당 소문자 variant를 포함한 process proxy env도 따릅니다. NO_PROXY / no_proxy는 여전히 api.telegram.org를 우회할 수 있습니다.
• 서비스 환경에서 OpenClaw managed proxy가 OPENCLAW_PROXY_URL을 통해 설정되고 표준 proxy env가 없으면, Telegram도 해당 URL을 Bot API transport에 사용합니다.
• 직접 egress/TLS가 불안정한 VPS host에서는 channels.telegram.proxy를 통해 Telegram API 호출을 라우팅하세요.

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

• Node 22+는 기본적으로 autoSelectFamily=true를 사용합니다(WSL2 제외). Telegram DNS 결과 순서는 OPENCLAW_TELEGRAM_DNS_RESULT_ORDER, channels.telegram.network.dnsResultOrder, NODE_OPTIONS=--dns-result-order=ipv4first 같은 프로세스 기본값 순으로 따릅니다. 적용되는 값이 없으면 Node 22+는 ipv4first로 폴백합니다.
• 호스트가 WSL2이거나 IPv4 전용 동작이 명시적으로 더 잘 작동한다면 패밀리 선택을 강제하세요.

channels:
  telegram:
    network:
      autoSelectFamily: false

• RFC 2544 벤치마크 범위 응답(198.18.0.0/15)은 기본적으로 이미 Telegram 미디어 다운로드에 허용됩니다. 신뢰할 수 있는 fake-IP 또는 투명 프록시가 미디어 다운로드 중 api.telegram.org를 다른 사설/내부/특수 용도 주소로 다시 쓴다면 Telegram 전용 우회를 옵트인할 수 있습니다.

channels:
  telegram:
    network:
      dangerouslyAllowPrivateNetwork: true

• 계정별로도 동일한 옵트인을 channels.telegram.accounts.<accountId>.network.dangerouslyAllowPrivateNetwork에서 사용할 수 있습니다.
• 프록시가 Telegram 미디어 호스트를 198.18.x.x로 확인한다면 먼저 위험 플래그를 꺼 둔 상태로 두세요. Telegram 미디어는 기본적으로 이미 RFC 2544 벤치마크 범위를 허용합니다.

• 환경 재정의(임시):
  • OPENCLAW_TELEGRAM_DISABLE_AUTO_SELECT_FAMILY=1
  • OPENCLAW_TELEGRAM_ENABLE_AUTO_SELECT_FAMILY=1
  • OPENCLAW_TELEGRAM_DNS_RESULT_ORDER=ipv4first
• DNS 응답을 검증하세요.

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