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

• 그룹 추가 허용/거부용 /setjoingroups
• 그룹 가시성 동작용 /setprivacy

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

• channels.telegram.streaming이 off | partial | block | progress여야 합니다(기본값: partial)
• progress는 Telegram에서 partial로 매핑됩니다(채널 간 명명 호환성용)
• 레거시 channels.telegram.streamMode와 불리언 streaming 값은 자동 매핑됩니다

• DM: OpenClaw는 동일한 미리보기 메시지를 유지하고 최종 편집을 그 자리에서 수행합니다(두 번째 메시지 없음)
• 그룹/토픽: OpenClaw는 동일한 미리보기 메시지를 유지하고 최종 편집을 그 자리에서 수행합니다(두 번째 메시지 없음)

• /reasoning stream은 생성 중 reasoning을 실시간 미리보기로 보냅니다
• 최종 답변은 reasoning 텍스트 없이 전송됩니다

• Markdown 유사 텍스트는 Telegram에 안전한 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
• 사용자 지정 명령은 기본 명령을 재정의할 수 없습니다
• 충돌/중복은 건너뛰고 로그에 기록됩니다

• 사용자 지정 명령은 메뉴 항목일 뿐이며 동작을 자동 구현하지 않습니다
• plugin/Skills 명령은 Telegram 메뉴에 표시되지 않아도 직접 입력하면 여전히 동작할 수 있습니다

• setMyCommands failed와 함께 BOT_COMMANDS_TOO_MUCH가 표시되면, 잘라낸 후에도 Telegram 메뉴가 여전히 넘친다는 뜻입니다. plugin/skill/사용자 지정 명령을 줄이거나 channels.telegram.commands.native를 비활성화하세요.
• setMyCommands failed와 함께 네트워크/fetch 오류가 표시되면 보통 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: "옵션을 선택하세요:",
  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)
• 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>를 덧붙입니다
• 응답과 입력 중 표시는 토픽 스레드를 대상으로 합니다
• 토픽 config 경로: 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
          }
        }
      }
    }
  }
}

• type: "acp" 및 match.channel: "telegram"이 있는 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는 현재 Telegram 토픽을 새 ACP 세션에 바인딩할 수 있습니다.
• 후속 토픽 메시지는 바인딩된 ACP 세션으로 직접 라우팅됩니다(/acp steer 불필요).
• OpenClaw는 성공적으로 바인딩한 후 생성 확인 메시지를 토픽 내에 고정합니다.
• channels.telegram.threadBindings.spawnAcpSessions=true가 필요합니다.

• MessageThreadId
• IsForum

• message_thread_id가 있는 개인 채팅은 DM 라우팅을 유지하지만 스레드 인식 세션 키/응답 대상을 사용합니다.

​

오디오 메시지

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

• ~/.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 액세스 제어(dmPolicy, allowFrom, groupPolicy, groupAllowFrom)를 따르며, 권한 없는 발신자는 버려집니다.
• Telegram은 반응 업데이트에 스레드 ID를 제공하지 않습니다.
  • 비포럼 그룹은 그룹 채팅 세션으로 라우팅
  • 포럼 그룹은 정확한 원래 토픽이 아니라 그룹 일반 토픽 세션(:topic:1)으로 라우팅

• channels.telegram.accounts.<accountId>.ackReaction
• channels.telegram.ackReaction
• messages.ackReaction
• agent identity 이모지 대체(agents.list[].identity.emoji, 없으면 ”👀”)

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

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

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

• channels.telegram.webhookUrl 설정
• channels.telegram.webhookSecret 설정(webhook URL이 설정된 경우 필수)
• 선택적 channels.telegram.webhookPath (기본값 /telegram-webhook)
• 선택적 channels.telegram.webhookHost (기본값 127.0.0.1)
• 선택적 channels.telegram.webhookPort (기본값 8787)

• channels.telegram.textChunkLimit 기본값은 4000입니다.
• channels.telegram.chunkMode="newline"은 길이 기준 분할 전에 문단 경계(빈 줄)를 우선합니다.
• channels.telegram.mediaMaxMb(기본값 100)는 인바운드 및 아웃바운드 Telegram 미디어 크기를 제한합니다.
• channels.telegram.timeoutSeconds는 Telegram API 클라이언트 타임아웃을 재정의합니다(설정하지 않으면 grammY 기본값 적용).
• 그룹 컨텍스트 기록은 channels.telegram.historyLimit 또는 messages.groupChat.historyLimit(기본값 50)을 사용하며, 0이면 비활성화됩니다.
• 응답/인용/전달 보조 컨텍스트는 현재 수신된 그대로 전달됩니다.
• Telegram allowlist는 주로 누가 agent를 트리거할 수 있는지 제어하며, 완전한 보조 컨텍스트 redaction 경계는 아닙니다.
• DM 기록 제어:
  • channels.telegram.dmHistoryLimit
  • channels.telegram.dms["<user_id>"].historyLimit
• channels.telegram.retry config는 복구 가능한 아웃바운드 API 오류에 대해 Telegram 전송 헬퍼(CLI/tools/actions)에 적용됩니다.

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
• 포럼 토픽용 --thread-id(또는 :topic: 대상 사용)

• channels.telegram.capabilities.inlineButtons가 허용할 때 인라인 키보드용 --buttons
• 아웃바운드 이미지와 GIF를 압축 사진 또는 애니메이션 미디어 업로드 대신 문서로 보내기 위한 --force-document

• channels.telegram.actions.sendMessage=false는 투표를 포함한 아웃바운드 Telegram 메시지를 비활성화합니다
• channels.telegram.actions.poll=false는 일반 전송은 유지한 채 Telegram 투표 생성을 비활성화합니다

• channels.telegram.execApprovals.enabled
• channels.telegram.execApprovals.approvers (선택 사항. 가능하면 allowFrom 및 direct defaultTo에서 추론된 숫자형 소유자 ID로 대체)
• channels.telegram.execApprovals.target (dm | channel | both, 기본값: dm)
• agentFilter, sessionFilter

• target: "dm"은 해석된 승인자 DM으로만 승인 프롬프트를 보냅니다
• target: "channel"은 원래 Telegram 채팅/토픽으로 프롬프트를 다시 보냅니다
• target: "both"는 승인자 DM과 원래 채팅/토픽 모두에 보냅니다

• plugin: 접두사가 있는 ID는 항상 plugin 승인으로 해석됩니다.
• 다른 승인 ID는 먼저 exec.approval.resolve를 시도합니다.
• Telegram이 plugin 승인에도 허용되어 있고 gateway가 exec 승인이 알 수 없거나 만료되었다고 말하면, Telegram은 한 번 plugin.approval.resolve를 통해 재시도합니다.
• 실제 exec 승인 거부/오류는 자동으로 plugin 승인 해석으로 넘어가지 않습니다.

• requireMention=false인 경우 Telegram 개인정보 보호 모드가 전체 가시성을 허용해야 합니다.
  • BotFather: /setprivacy -> 비활성화
  • 그런 다음 그룹에서 봇을 제거했다가 다시 추가
• openclaw channels status는 config가 멘션 없는 그룹 메시지를 기대할 때 경고를 표시합니다.
• openclaw channels status --probe는 명시적 숫자형 그룹 ID를 검사할 수 있습니다. 와일드카드 "*"는 멤버십 probe를 할 수 없습니다.
• 빠른 세션 테스트: /activation always.

• channels.telegram.groups가 존재하면, 해당 그룹이 목록에 있거나 "*"가 포함되어 있어야 합니다
• 그룹 내 봇 멤버십 확인
• 건너뛴 이유는 openclaw logs --follow에서 로그 검토

• 발신자 ID를 인증하세요(페어링 및/또는 숫자형 allowFrom)
• 그룹 정책이 open이더라도 명령 인증은 여전히 적용됩니다
• setMyCommands failed와 함께 BOT_COMMANDS_TOO_MUCH가 표시되면 기본 메뉴 항목이 너무 많다는 뜻입니다. plugin/skill/사용자 지정 명령을 줄이거나 기본 메뉴를 비활성화하세요
• setMyCommands failed와 함께 네트워크/fetch 오류가 표시되면 보통 api.telegram.org에 대한 DNS/HTTPS 도달성 문제를 의미합니다

• Node 22+와 사용자 지정 fetch/proxy 조합은 AbortSignal 타입이 맞지 않으면 즉시 abort 동작을 유발할 수 있습니다.
• 일부 호스트는 api.telegram.org를 먼저 IPv6로 해석하므로, IPv6 아웃바운드가 깨져 있으면 간헐적인 Telegram API 실패가 발생할 수 있습니다.
• 로그에 TypeError: fetch failed 또는 Network request for 'getUpdates' failed!가 포함되면, OpenClaw는 이제 이를 복구 가능한 네트워크 오류로 재시도합니다.
• 직접 아웃바운드/TLS가 불안정한 VPS 호스트에서는 Telegram API 호출을 channels.telegram.proxy를 통해 라우팅하세요:

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

• Node 22+는 기본적으로 autoSelectFamily=true(WSL2 제외) 및 dnsResultOrder=ipv4first를 사용합니다.
• 호스트가 WSL2이거나 IPv4 전용 동작이 명시적으로 더 잘 맞는 경우, family selection을 강제하세요:

channels:
  telegram:
    network:
      autoSelectFamily: false

• RFC 2544 벤치마크 범위 응답(198.18.0.0/15)은 기본적으로 Telegram 미디어 다운로드에 이미 허용되어 있습니다. 신뢰할 수 있는 가짜 IP 또는 transparent proxy가 미디어 다운로드 중 api.telegram.org를 다른 private/internal/special-use 주소로 재작성하는 경우, Telegram 전용 우회를 선택적으로 활성화할 수 있습니다:

channels:
  telegram:
    network:
      dangerouslyAllowPrivateNetwork: true

• 동일한 선택 기능은 계정별로도 사용할 수 있습니다: channels.telegram.accounts.<accountId>.network.dangerouslyAllowPrivateNetwork.
• proxy가 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