• /setprivacy를 통해 프라이버시 모드를 비활성화하거나,
• 봇을 그룹 관리자로 설정합니다.

• /setjoingroups로 그룹 추가 허용/거부
• /setprivacy로 그룹 가시성 행동 제어

• channels.telegram.streamMode가 "off"가 아닌 경우 (기본값: "partial")

• off: 라이브 미리보기 없음
• partial: 부분 텍스트로 빈번한 미리보기 업데이트
• block: channels.telegram.draftChunk를 사용하는 청크 미리보기 업데이트

• minChars: 200
• maxChars: 800
• breakPreference: "paragraph"

• /reasoning stream은 생성 중인 동안 라이브 미리보기에 이유를 보냅니다
• 최종 해답은 이유 텍스트 없이 전송됩니다

• Markdown 유사 텍스트는 Telegram-safe HTML로 렌더링됩니다.
• 모델 HTML 원본은 Telegram 파싱 오류를 줄이기 위해 이스케이프됩니다.
• Telegram이 파싱된 HTML을 거부하면, OpenClaw는 평문 텍스트로 다시 시도합니다.

• commands.native: "auto"는 Telegram에 대해 네이티브 명령어를 활성화합니다

{
  channels: {
    telegram: {
      customCommands: [
        { command: "backup", description: "Git 백업" },
        { command: "generate", description: "이미지 생성" },
      ],
    },
  },
}

• 이름은 정규화됩니다 (선행 / 제거, 소문자)
• 유효한 패턴: a-z, 0-9, _, 길이 1..32
• 사용자 정의 명령어는 네이티브 명령어를 재정의할 수 없음
• 충돌/중복은 건너뛰고 로그됨

• 사용자 정의 명령어는 메뉴 항목일 뿐입니다; 자동으로 동작을 구현하지 않음
• 플러그인/스킬 명령어는 Telegram 메뉴에 표시되지 않더라도 입력할 수 있음

• setMyCommands failed는 보통 api.telegram.org에 대한 DNS/HTTPS 접근성 문제가 있다는 것을 의미합니다.

​

디바이스 페어링 명령어 (device-pair 플러그인)

1. /pair는 설정 코드를 생성합니다
2. 코드를 iOS 앱에 붙여 넣기
3. /pair approve는 최신 대기 요청을 승인합니다

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

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

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

{
  action: "send",
  channel: "telegram",
  to: "123456789",
  message: "옵션을 선택하세요:",
  buttons: [
    [
      { text: "예", callback_data: "yes" },
      { text: "아니오", callback_data: "no" },
    ],
    [{ text: "취소", callback_data: "cancel" }],
  ],
}

• sendMessage (to, content, 선택적 mediaUrl, replyToMessageId, messageThreadId)
• react (chatId, messageId, emoji)
• deleteMessage (chatId, messageId)
• editMessage (chatId, messageId, content)

• channels.telegram.actions.sendMessage
• channels.telegram.actions.editMessage
• 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를 포함합니다

• MessageThreadId
• IsForum

• message_thread_id를 가진 프라이빗 채팅은 DM 라우팅을 유지하지만 스레드 인식 세션 키/응답 타깃을 사용합니다.

​

오디오 메시지

• 기본값: 오디오 파일 동작
• [[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

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

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

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

{
  action: "sticker-search",
  channel: "telegram",
  query: "고양이 휘적휘적",
  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은 반응 업데이트에 스레드 ID를 제공하지 않음
  • 포럼이 아닌 그룹은 그룹 채팅 세션으로 라우팅됨
  • 포럼 그룹은 그룹 일반 주제 세션 (:topic:1)으로 라우팅되며, 정확한 시작 주제가 아님

• channels.telegram.accounts.<accountId>.ackReaction
• channels.telegram.ackReaction
• messages.ackReaction
• 에이전트 아이덴티티 이모지 대체 (agents.list[].identity.emoji , 그렇지 않으면 ”👀”)

• Telegram은 유니코드 이모지를 기대합니다 (예: ”👀”).
• 특정 채널이나 계정에 대해 이 반응을 비활성화하려면 ""을 사용하세요.

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

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

• channels.telegram.webhookUrl 설정
• channels.telegram.webhookSecret 설정 (웹훅 URL 설정 시 필수)
• 선택적 channels.telegram.webhookPath (기본 /telegram-webhook)
• 선택적 channels.telegram.webhookHost (기본 127.0.0.1)

• channels.telegram.textChunkLimit 기본은 4000입니다.
• channels.telegram.chunkMode="newline"은 길이 분할 전에 단락 경계를 (빈 줄) 선호합니다.
• channels.telegram.mediaMaxMb (기본값 5)는 수신 Telegram 미디어 다운로드/처리 크기를 제한합니다.
• channels.telegram.timeoutSeconds는 Telegram API 클라이언트 타임아웃을 재정의합니다 (설정되지 않으면 grammY 기본값이 적용됩니다).
• 그룹 컨텍스트 히스토리는 channels.telegram.historyLimit 또는 messages.groupChat.historyLimit을 사용합니다 (기본값 50); 0은 비활성화.
• DM 히스토리 컨트롤:
  • channels.telegram.dmHistoryLimit
  • channels.telegram.dms["<user_id>"].historyLimit
• 아웃바운드 Telegram API 재시도는 channels.telegram.retry로 구성할 수 있습니다.

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

• requireMention=false인 경우, Telegram 프라이버시 모드는 전체 가시성을 허용해야 합니다.
  • BotFather: /setprivacy -> 비활성화
  • 그런 다음 그룹에서 봇 제거 + 재추가
• openclaw channels status는 구성에서 언급되지 않은 그룹 메시지를 기대할 때 경고를 표시합니다.
• openclaw channels status --probe는 명시적 숫자 그룹 ID를 확인할 수 있습니다; 와일드카드 "*"은 멤버십을 검사할 수 없습니다.
• 빠른 세션 테스트: /activation always.

• channels.telegram.groups가 있는 경우, 그룹이 나열되어 있어야 함 (또는 "*" 포함)
• 그룹에서 봇의 멤버십 확인
• 스킵 이유를 확인하려면 로그 검토: openclaw logs --follow

• 발신자 ID 권한 부여 (페어링 및/또는 숫자 allowFrom)
• 명령어 권한 부여는 그룹 정책이 open일 때도 계속 적용됩니다
• setMyCommands failed는 보통 api.telegram.org에 대한 DNS/HTTPS 도달 가능성 문제를 나타냅니다

• Node 22+ + 사용자 정의 fetch/프록시가 임의의 중단 동작을 트리거하여 AbortSignal 유형 불일치가 발생할 수 있습니다.
• 일부 호스트는 api.telegram.org를 먼저 IPv6로 해석합니다; IPv6 유출이 잘못되면 Telegram API 오류 간헐적으로 발생할 수 있습니다.
• DNS 응답을 검증:

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