Telegram

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

• 그룹 추가 허용/거부를 위한 /setjoingroups
• 그룹 표시 동작을 위한 /setprivacy

• 다이렉트 채팅: 미리보기 메시지 + editMessageText
• 그룹/토픽: 미리보기 메시지 + editMessageText

• channels.telegram.streaming은 off | partial | block | progress입니다(기본값: partial).
• progress는 도구 진행 상황을 위한 편집 가능한 상태 초안 하나를 유지하고, 완료 시 이를 지운 뒤 최종 답변을 일반 메시지로 보냅니다.
• streaming.preview.toolProgress는 도구/진행 상황 업데이트가 동일한 편집된 미리보기 메시지를 재사용할지 제어합니다(기본값: 미리보기 스트리밍이 활성 상태일 때 true).
• streaming.preview.commandText는 해당 도구 진행 상황 줄 안의 명령/실행 세부 정보를 제어합니다: raw(기본값, 릴리스된 동작 유지) 또는 status(도구 레이블만).
• 기존 channels.telegram.streamMode 및 불리언 streaming 값은 감지됩니다. 이를 channels.telegram.streaming.mode로 마이그레이션하려면 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/그룹/토픽 미리보기: OpenClaw는 동일한 미리보기 메시지를 유지하고 최종 편집을 그 자리에서 수행합니다.
• 여러 Telegram 메시지로 분할되는 긴 텍스트 최종본은 가능한 경우 기존 미리보기를 첫 번째 최종 청크로 재사용한 뒤 나머지 청크만 보냅니다.
• progress 모드 최종본은 상태 초안을 지우고 초안을 답변으로 편집하는 대신 일반 최종 전달을 사용합니다.
• 완료된 텍스트가 확인되기 전에 최종 편집이 실패하면 OpenClaw는 일반 최종 전달을 사용하고 오래된 미리보기를 정리합니다.

• /reasoning stream은 생성 중 reasoning을 실시간 미리보기로 보냅니다.
• reasoning 미리보기는 최종 전달 후 삭제됩니다. reasoning이 계속 표시되어야 하면 /reasoning on을 사용하세요.
• 최종 답변은 reasoning 텍스트 없이 전송됩니다.

• Markdown 비슷한 텍스트는 Telegram 안전 HTML로 렌더링됩니다.
• 지원되는 Telegram HTML 태그는 유지되고, 지원되지 않는 HTML은 이스케이프됩니다.
• Telegram이 파싱된 HTML을 거부하면 OpenClaw는 일반 텍스트로 다시 시도합니다.

• commands.native: "auto"는 Telegram용 네이티브 명령을 활성화합니다.

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

• 이름은 정규화됩니다(앞의 / 제거, 소문자 변환).
• 유효한 패턴: a-z, 0-9, _, 길이 1..32
• 사용자 지정 명령은 네이티브 명령을 재정의할 수 없습니다.
• 충돌/중복은 건너뛰고 로그에 기록됩니다.

• 사용자 지정 명령은 메뉴 항목일 뿐이며, 동작을 자동으로 구현하지는 않습니다.
• Plugin/Skills 명령은 Telegram 메뉴에 표시되지 않더라도 입력하면 계속 작동할 수 있습니다.

• BOT_COMMANDS_TOO_MUCH와 함께 setMyCommands failed가 표시되면 잘라낸 후에도 Telegram 메뉴가 여전히 초과되었다는 뜻입니다. Plugin/Skills/사용자 지정 명령을 줄이거나 channels.telegram.commands.native를 비활성화하세요.
• 직접 Bot API curl 명령은 작동하는데 deleteWebhook, deleteMyCommands 또는 setMyCommands가 404: Not Found로 실패하면 channels.telegram.apiRoot가 전체 /bot<TOKEN> 엔드포인트로 설정되었을 수 있습니다. apiRoot는 Bot API 루트만이어야 하며, openclaw doctor --fix는 실수로 붙은 끝의 /bot<TOKEN>을 제거합니다.
• getMe returned 401은 Telegram이 구성된 봇 토큰을 거부했다는 뜻입니다. 현재 BotFather 토큰으로 botToken, tokenFile 또는 TELEGRAM_BOT_TOKEN을 업데이트하세요. OpenClaw는 폴링 전에 중지되므로 이는 Webhook 정리 실패로 보고되지 않습니다.
• 네트워크/fetch 오류와 함께 setMyCommands failed가 표시되면 보통 api.telegram.org로 나가는 DNS/HTTPS가 차단되었다는 뜻입니다.

​

기기 페어링 명령(device-pair Plugin)

1. /pair가 설정 코드를 생성합니다.
2. iOS 앱에 코드를 붙여넣습니다.
3. /pair pending은 대기 중인 요청(역할/범위 포함)을 나열합니다.
4. 요청을 승인합니다.
   • 명시적 승인은 /pair approve <requestId>
   • 대기 중인 요청이 하나뿐이면 /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" }],
  ],
}

• sendMessage(to, content, 선택 사항 mediaUrl, replyToMessageId, messageThreadId)
• react(chatId, messageId, emoji)
• deleteMessage(chatId, messageId)
• editMessage(chatId, messageId, content)
• 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
          }
        }
      }
    }
  }
}

​

오디오 메시지

• 기본값: 오디오 파일 동작
• 에이전트 reply에 태그 [[audio_as_voice]]를 넣어 음성 메모 전송을 강제
• 수신 음성 메모 전사는 에이전트 컨텍스트에서 기계 생성의 신뢰할 수 없는 텍스트로 프레이밍됩니다. mention 감지는 여전히 원시 전사를 사용하므로 mention으로 제한된 음성 메시지도 계속 작동합니다.

{
  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: 다운로드 및 처리됨(placeholder <media:sticker>)
• 애니메이션 TGS: 건너뜀
• 비디오 WEBM: 건너뜀

• 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: "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은 봇이 보낸 메시지에 대한 사용자 reaction만 의미합니다(전송 메시지 캐시를 통한 최선 노력).
• Reaction event는 여전히 Telegram access control(dmPolicy, allowFrom, groupPolicy, groupAllowFrom)을 따릅니다. 권한 없는 발신자는 삭제됩니다.
• Telegram은 reaction update에서 thread ID를 제공하지 않습니다.
  • non-forum 그룹은 그룹 채팅 session으로 라우팅됩니다
  • forum 그룹은 정확한 원래 topic이 아니라 그룹 general-topic session(:topic:1)으로 라우팅됩니다

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

• Telegram은 unicode emoji를 기대합니다(예: ”👀”).
• 채널 또는 계정에 대해 reaction을 비활성화하려면 ""를 사용하세요.

• channels.telegram.groups를 업데이트하기 위한 그룹 migration event(migrate_to_chat_id)
• /config set 및 /config unset(command 활성화 필요)

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

• channels.telegram.textChunkLimit 기본값은 4000입니다.
• channels.telegram.chunkMode="newline"은 길이 분할 전에 문단 경계(빈 줄)를 우선합니다.
• channels.telegram.mediaMaxMb(기본값 100)는 수신 및 발신 Telegram media 크기를 제한합니다.
• channels.telegram.mediaGroupFlushMs(기본값 500)는 Telegram album/media group이 OpenClaw에서 하나의 수신 메시지로 dispatch되기 전에 버퍼링되는 시간을 제어합니다. album 부분이 늦게 도착하면 값을 늘리고, album reply 지연 시간을 줄이려면 값을 줄이세요.
• channels.telegram.timeoutSeconds는 Telegram API client timeout을 재정의합니다(설정하지 않으면 grammY 기본값이 적용됨). bot client는 구성된 값을 60초 발신 text/typing request guard 아래로 제한하므로 grammY가 OpenClaw의 transport guard와 fallback이 실행되기 전에 보이는 reply delivery를 중단하지 않습니다. long polling은 여전히 45초 getUpdates request guard를 사용하므로 idle poll이 무기한 방치되지 않습니다.
• channels.telegram.pollingStallThresholdMs 기본값은 120000입니다. false-positive polling-stall restart에 대해서만 30000에서 600000 사이로 조정하세요.
• 그룹 컨텍스트 history는 channels.telegram.historyLimit 또는 messages.groupChat.historyLimit(기본값 50)을 사용합니다. 0은 비활성화합니다.
• reply/quote/forward 보조 컨텍스트는 Gateway가 parent message를 관찰한 경우 하나의 선택된 conversation context window로 정규화됩니다. 관찰된 메시지 캐시는 session store 옆에 유지됩니다. Telegram은 update에 하나의 얕은 reply_to_message만 포함하므로, 캐시보다 오래된 chain은 Telegram의 현재 update payload로 제한됩니다.
• Telegram allowlist는 주로 agent를 트리거할 수 있는 사람을 제한하며, 전체 보조 컨텍스트 redaction boundary가 아닙니다.
• DM history 제어:
  • channels.telegram.dmHistoryLimit
  • channels.telegram.dms["<user_id>"].historyLimit
• channels.telegram.retry 설정은 복구 가능한 발신 API error에 대해 Telegram send helper(CLI/tools/actions)에 적용됩니다. 수신 final-reply delivery도 Telegram pre-connect failure에 대해 제한된 safe-send retry를 사용하지만, 보이는 메시지를 중복시킬 수 있는 모호한 post-send network 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: target 사용)

• channels.telegram.capabilities.inlineButtons가 허용할 때 inline keyboard용 buttons block이 있는 --presentation
• bot이 해당 채팅에서 pin할 수 있을 때 pinned delivery를 요청하는 --pin 또는 --delivery '{"pin":true}'
• 발신 이미지, GIF, 비디오를 압축된 photo, animated-media 또는 video upload 대신 document로 보내는 --force-document

• channels.telegram.actions.sendMessage=false는 poll을 포함한 발신 Telegram 메시지를 비활성화합니다
• channels.telegram.actions.poll=false는 일반 send를 활성 상태로 유지하면서 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 개인정보 보호 모드에서 전체 표시를 허용해야 합니다.
  • BotFather: /setprivacy -> Disable
  • 그런 다음 그룹에서 봇을 제거한 뒤 다시 추가합니다.
• 구성이 멘션되지 않은 그룹 메시지를 예상할 때 openclaw channels status가 경고합니다.
• openclaw channels status --probe는 명시적인 숫자 그룹 ID를 확인할 수 있습니다. 와일드카드 "*"는 멤버십 조사를 할 수 없습니다.
• 빠른 세션 테스트: /activation always.

• channels.telegram.groups가 있으면 그룹이 목록에 있어야 합니다(또는 "*" 포함).
• 그룹 내 봇 멤버십을 확인합니다.
• 건너뛴 이유를 보려면 로그를 검토합니다: openclaw logs --follow

• 보낸 사람 ID를 승인합니다(페어링 및/또는 숫자 allowFrom).
• 그룹 정책이 open이어도 명령 승인은 계속 적용됩니다.
• BOT_COMMANDS_TOO_MUCH와 함께 setMyCommands failed가 발생하면 네이티브 메뉴 항목이 너무 많다는 뜻입니다. Plugin/skill/사용자 지정 명령을 줄이거나 네이티브 메뉴를 비활성화하세요.
• 시작 시 deleteMyCommands / setMyCommands 호출과 sendChatAction 입력 표시 호출은 제한 시간이 적용되며, 요청 제한 시간 초과 시 Telegram 전송 대체 경로를 통해 한 번 재시도됩니다. 지속적인 네트워크/가져오기 오류는 보통 api.telegram.org에 대한 DNS/HTTPS 도달성 문제를 나타냅니다.

• getMe returned 401은 구성된 봇 토큰에 대한 Telegram 인증 실패입니다.
• BotFather에서 봇 토큰을 다시 복사하거나 재생성한 뒤, 기본 계정에 대해 channels.telegram.botToken, channels.telegram.tokenFile, channels.telegram.accounts.<id>.botToken 또는 TELEGRAM_BOT_TOKEN을 업데이트합니다.
• 시작 중 deleteWebhook 401 Unauthorized도 인증 실패입니다. 이를 “웹훅이 없음”으로 처리하면 동일한 잘못된 토큰 실패가 이후 API 호출로 미뤄질 뿐입니다.

• Node 22+와 사용자 지정 fetch/proxy 조합은 AbortSignal 타입이 일치하지 않으면 즉시 중단 동작을 유발할 수 있습니다.
• 일부 호스트는 api.telegram.org를 IPv6로 먼저 확인합니다. 손상된 IPv6 송신은 간헐적인 Telegram API 실패를 일으킬 수 있습니다.
• 로그에 TypeError: fetch failed 또는 Network request for 'getUpdates' failed!가 포함되면 OpenClaw는 이제 이를 복구 가능한 네트워크 오류로 재시도합니다.
• 폴링 시작 중 OpenClaw는 성공한 시작 getMe 조사를 grammY에 재사용하므로 러너가 첫 getUpdates 전에 두 번째 getMe를 수행할 필요가 없습니다.
• 폴링 시작 중 일시적인 네트워크 오류로 deleteWebhook이 실패하면 OpenClaw는 다른 사전 폴링 제어 플레인 호출을 수행하지 않고 long polling으로 계속 진행합니다. 아직 활성 상태인 웹훅은 getUpdates 충돌로 드러납니다. 그러면 OpenClaw가 Telegram 전송을 다시 빌드하고 웹훅 정리를 재시도합니다.
• Telegram 소켓이 짧고 고정된 주기로 재활용되면 낮은 channels.telegram.timeoutSeconds를 확인하세요. 봇 클라이언트는 송신 및 getUpdates 요청 보호값보다 낮게 구성된 값을 제한하지만, 이전 릴리스에서는 이 값이 보호값보다 낮게 설정되면 모든 폴링 또는 응답이 중단될 수 있었습니다.
• 로그에 Polling stall detected가 포함되면 OpenClaw는 기본적으로 완료된 long-poll 활성 확인이 120초 동안 없을 때 폴링을 다시 시작하고 Telegram 전송을 다시 빌드합니다.
• openclaw channels status --probe와 openclaw doctor는 실행 중인 폴링 계정이 시작 유예 후 getUpdates를 완료하지 않았거나, 실행 중인 웹훅 계정이 시작 유예 후 setWebhook을 완료하지 않았거나, 마지막으로 성공한 폴링 전송 활동이 오래된 경우 경고합니다.
• 장시간 실행되는 getUpdates 호출은 정상인데도 호스트가 잘못된 폴링 중단 재시작을 계속 보고할 때만 channels.telegram.pollingStallThresholdMs를 늘리세요. 지속적인 중단은 보통 호스트와 api.telegram.org 사이의 프록시, DNS, IPv6 또는 TLS 송신 문제를 가리킵니다.
• Telegram은 Bot API 전송에 대해 HTTP_PROXY, HTTPS_PROXY, ALL_PROXY와 그 소문자 변형을 포함한 프로세스 프록시 환경도 따릅니다. NO_PROXY / no_proxy는 여전히 api.telegram.org를 우회할 수 있습니다.
• 서비스 환경에서 OpenClaw 관리형 프록시가 OPENCLAW_PROXY_URL을 통해 구성되어 있고 표준 프록시 환경이 없으면, Telegram도 Bot API 전송에 해당 URL을 사용합니다.
• 직접 송신/TLS가 불안정한 VPS 호스트에서는 Telegram API 호출을 channels.telegram.proxy를 통해 라우팅합니다.

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