Telegram (Bot API)

Telegram 봇은 기본적으로 **프라이버시 모드**로 되어 있어 수신하는 그룹 메시지가 제한됩니다.

봇이 모든 그룹 메시지를 볼 수 있어야 하는 경우:

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

프라이버시 모드를 전환할 때 Telegram이 변경 사항을 적용하도록 각 그룹에서 봇을 제거 + 다시 추가합니다.

관리자 상태는 Telegram 그룹 설정에서 제어됩니다.

관리자 봇은 모든 그룹 메시지를 수신하므로 항상 켜진 그룹 동작에 유용합니다.

- `/setjoingroups`로 그룹 추가 허용/거부
- `/setprivacy`로 그룹 가시성 동작

OpenClaw는 부분 응답을 실시간으로 스트리밍할 수 있습니다:

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

요구 사항:

- `channels.telegram.streaming`은 `off | partial | block | progress` (기본: `partial`)
- `progress`는 Telegram에서 `partial`로 매핑됩니다 (크로스 채널 네이밍 호환)
- 레거시 `channels.telegram.streamMode` 및 불리언 `streaming` 값은 자동 매핑됩니다

텍스트 전용 응답:

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

복합 응답 (예: 미디어 페이로드)의 경우 OpenClaw는 일반 최종 전달로 폴백하고 미리보기 메시지를 정리합니다.

미리보기 스트리밍은 블록 스트리밍과 별개입니다. Telegram에 블록 스트리밍이 명시적으로 활성화되면 OpenClaw는 이중 스트리밍을 방지하기 위해 미리보기 스트림을 건너뜁니다.

네이티브 초안 전송이 불가능/거부되면 OpenClaw는 자동으로 `sendMessage` + `editMessageText`로 폴백합니다.

Telegram 전용 추론 스트림:

- `/reasoning stream`은 생성 중 실시간 미리보기에 추론을 전송합니다
- 최종 답변은 추론 텍스트 없이 전송됩니다

아웃바운드 텍스트는 Telegram `parse_mode: "HTML"`을 사용합니다.

- 마크다운 스타일 텍스트는 Telegram 안전 HTML로 렌더링됩니다.
- 원시 모델 HTML은 Telegram 파싱 실패를 줄이기 위해 이스케이프됩니다.
- Telegram이 파싱된 HTML을 거부하면 OpenClaw는 일반 텍스트로 재시도합니다.

링크 미리보기는 기본적으로 활성화되며 `channels.telegram.linkPreview: false`로 비활성화할 수 있습니다.

Telegram 명령 메뉴 등록은 시작 시 `setMyCommands`로 처리됩니다.

네이티브 명령 기본값:

- `commands.native: "auto"`는 Telegram에서 네이티브 명령을 활성화합니다

사용자 정의 명령 메뉴 항목 추가:

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

규칙:

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

참고:

- 사용자 정의 명령은 메뉴 항목만이며 동작을 자동 구현하지 않음
- 플러그인/스킬 명령은 Telegram 메뉴에 표시되지 않아도 입력하면 작동 가능

네이티브 명령이 비활성화되면 내장 명령이 제거됩니다. 사용자 정의/플러그인 명령은 설정된 경우 여전히 등록될 수 있습니다.

일반적인 설정 실패:

- `BOT_COMMANDS_TOO_MUCH`로 `setMyCommands failed`는 트리밍 후에도 Telegram 메뉴가 오버플로되었음을 의미합니다. 플러그인/스킬/사용자 정의 명령을 줄이거나 `channels.telegram.commands.native`를 비활성화합니다.
- 네트워크/fetch 오류로 `setMyCommands failed`는 일반적으로 `api.telegram.org`로의 아웃바운드 DNS/HTTPS가 차단되었음을 의미합니다.

### 기기 페어링 명령 (`device-pair` 플러그인)

`device-pair` 플러그인이 설치된 경우:

1. `/pair`로 설정 코드 생성
2. iOS 앱에 코드 붙여넣기
3. `/pair approve`로 최신 대기 중 요청 승인

자세히: [Pairing](/docs/channels/pairing#pair-via-telegram-recommended-for-ios).

인라인 키보드 범위 설정:

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

계정별 재정의:

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

범위:

- `off`
- `dm`
- `group`
- `all`
- `allowlist` (기본값)

레거시 `capabilities: ["inlineButtons"]`는 `inlineButtons: "all"`로 매핑됩니다.

메시지 액션 예시:

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

콜백 클릭은 에이전트에게 텍스트로 전달됩니다:
`callback_data: <value>`

Telegram 도구 액션 포함:

- `sendMessage` (`to`, `content`, 선택 `mediaUrl`, `replyToMessageId`, `messageThreadId`)
- `react` (`chatId`, `messageId`, `emoji`)
- `deleteMessage` (`chatId`, `messageId`)
- `editMessage` (`chatId`, `messageId`, `content`)
- `createForumTopic` (`chatId`, `name`, 선택 `iconColor`, `iconCustomEmojiId`)

채널 메시지 액션은 편의 별칭을 노출합니다 (`send`, `react`, `delete`, `edit`, `sticker`, `sticker-search`, `topic-create`).

게이팅 제어:

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

참고: `edit`과 `topic-create`는 현재 기본적으로 활성화되어 있으며 별도의 `channels.telegram.actions.*` 토글이 없습니다.
런타임 전송은 활성 설정/시크릿 스냅샷(시작/리로드)을 사용하므로 액션 경로는 전송마다 임시 SecretRef 재해석을 수행하지 않습니다.

리액션 제거 의미: [/tools/reactions](/docs/tools/reactions)

Telegram은 생성된 출력에서 명시적 응답 스레딩 태그를 지원합니다:

- `[[reply_to_current]]`는 트리거 메시지에 응답
- `[[reply_to:<id>]]`는 특정 Telegram 메시지 ID에 응답

`channels.telegram.replyToMode`로 처리를 제어합니다:

- `off` (기본값)
- `first`
- `all`

참고: `off`는 암묵적 응답 스레딩을 비활성화합니다. 명시적 `[[reply_to_*]]` 태그는 여전히 적용됩니다.

포럼 슈퍼그룹:

- 토픽 세션 키에 `:topic:<threadId>` 추가
- 응답 및 입력 표시가 토픽 스레드를 대상으로 함
- 토픽 설정 경로:
  `channels.telegram.groups.<chatId>.topics.<threadId>`

일반 토픽 (`threadId=1`) 특수 케이스:

- 메시지 전송 시 `message_thread_id` 생략 (Telegram이 `sendMessage(...thread_id=1)`을 거부)
- 입력 중 액션에는 여전히 `message_thread_id` 포함

토픽 상속: 토픽 항목은 재정의하지 않는 한 그룹 설정을 상속합니다 (`requireMention`, `allowFrom`, `skills`, `systemPrompt`, `enabled`, `groupPolicy`).
`agentId`는 토픽 전용이며 그룹 기본값을 상속하지 않습니다.

**토픽별 에이전트 라우팅**: 각 토픽은 토픽 설정에서 `agentId`를 설정하여 다른 에이전트로 라우팅할 수 있습니다. 이를 통해 각 토픽이 자체 격리된 작업 공간, 메모리, 세션을 갖게 됩니다. 예시:

```json5
{
  channels: {
    telegram: {
      groups: {
        "-1001234567890": {
          topics: {
            "1": { agentId: "main" },      // 일반 토픽 -> main 에이전트
            "3": { agentId: "zu" },        // Dev 토픽 -> zu 에이전트
            "5": { agentId: "coder" }      // 코드 리뷰 -> coder 에이전트
          }
        }
      }
    }
  }
}
```

각 토픽은 자체 세션 키를 갖습니다: `agent:zu:telegram:group:-1001234567890:topic:3`

**영구 ACP 토픽 바인딩**: 포럼 토픽은 최상위 타입 ACP 바인딩을 통해 ACP 하네스 세션을 고정할 수 있습니다:

- `bindings[]`에 `type: "acp"` 및 `match.channel: "telegram"`

예시:

```json5
{
  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 생성**:

- `/acp spawn <agent> --thread here|auto`는 현재 Telegram 토픽을 새 ACP 세션에 바인딩할 수 있습니다.
- 후속 토픽 메시지는 바인딩된 ACP 세션으로 직접 라우팅됩니다 (`/acp steer` 불필요).
- OpenClaw는 바인딩 성공 후 토픽 내에서 생성 확인 메시지를 고정합니다.
- `channels.telegram.threadBindings.spawnAcpSessions=true`가 필요합니다.

템플릿 컨텍스트 포함:

- `MessageThreadId`
- `IsForum`

DM 스레드 동작:

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

### 오디오 메시지

Telegram은 음성 메모와 오디오 파일을 구분합니다.

- 기본: 오디오 파일 동작
- 에이전트 응답에 `[[audio_as_voice]]` 태그로 음성 메모 전송 강제

메시지 액션 예시:

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

### 비디오 메시지

Telegram은 비디오 파일과 비디오 노트를 구분합니다.

메시지 액션 예시:

{
  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: "cat waving",
  limit: 5,
}

Telegram 리액션은 `message_reaction` 업데이트로 도착합니다 (메시지 페이로드와 별도).

활성화되면 OpenClaw가 다음과 같은 시스템 이벤트를 큐에 넣습니다:

- `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`)으로 라우팅됩니다

폴링/웹훅의 `allowed_updates`에 `message_reaction`이 자동으로 포함됩니다.

`ackReaction`은 OpenClaw가 인바운드 메시지를 처리하는 동안 확인 이모지를 전송합니다.

해석 순서:

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

참고:

- Telegram은 유니코드 이모지를 사용합니다 (예: "👀").
- `""`를 사용하여 채널 또는 계정에서 리액션을 비활성화합니다.

채널 설정 쓰기는 기본적으로 활성화됩니다 (`configWrites !== false`).

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.webhookPort` (기본 `8787`)

웹훅 모드의 기본 로컬 리스너는 `127.0.0.1:8787`에 바인딩됩니다.

공개 엔드포인트가 다른 경우 리버스 프록시를 앞에 두고 `webhookUrl`을 공개 URL로 지정합니다.
의도적으로 외부 인그레스가 필요한 경우 `webhookHost`를 설정합니다 (예: `0.0.0.0`).

- `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`으로 비활성화.
- DM 히스토리 제어:
  - `channels.telegram.dmHistoryLimit`
  - `channels.telegram.dms["<user_id>"].historyLimit`
- `channels.telegram.retry` 설정은 복구 가능한 아웃바운드 API 오류에 대한 Telegram 전송 헬퍼(CLI/도구/액션)에 적용됩니다.

CLI 전송 대상은 숫자 채팅 ID 또는 사용자 이름일 수 있습니다:

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

Telegram 설문조사는 `openclaw message poll`을 사용하며 포럼 토픽을 지원합니다:

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

Telegram 전용 설문조사 플래그:

- `--poll-duration-seconds` (5-600)
- `--poll-anonymous`
- `--poll-public`
- `--thread-id` 포럼 토픽용 (또는 `:topic:` 대상 사용)

액션 게이팅:

- `channels.telegram.actions.sendMessage=false`는 설문조사를 포함한 아웃바운드 Telegram 메시지를 비활성화합니다
- `channels.telegram.actions.poll=false`는 일반 전송을 유지하면서 Telegram 설문조사 생성을 비활성화합니다

Telegram은 승인자 DM에서 실행 승인을 지원하며 원본 채팅 또는 토픽에 승인 프롬프트를 선택적으로 게시할 수 있습니다.

설정 경로:

- `channels.telegram.execApprovals.enabled`
- `channels.telegram.execApprovals.approvers`
- `channels.telegram.execApprovals.target` (`dm` | `channel` | `both`, 기본: `dm`)
- `agentFilter`, `sessionFilter`

승인자는 숫자형 Telegram 사용자 ID여야 합니다. `enabled`가 false이거나 `approvers`가 비어있으면 Telegram은 실행 승인 클라이언트로 작동하지 않습니다. 승인 요청은 다른 설정된 승인 경로 또는 실행 승인 폴백 정책으로 폴백됩니다.

전달 규칙:

- `target: "dm"`은 설정된 승인자 DM에만 승인 프롬프트 전송
- `target: "channel"`은 원본 Telegram 채팅/토픽에 프롬프트 전송
- `target: "both"`는 승인자 DM과 원본 채팅/토픽 모두에 전송

설정된 승인자만 승인 또는 거부할 수 있습니다. 비승인자는 `/approve`를 사용할 수 없으며 Telegram 승인 버튼도 사용할 수 없습니다.

채널 전달은 채팅에 명령 텍스트를 표시하므로 신뢰할 수 있는 그룹/토픽에서만 `channel` 또는 `both`를 활성화합니다. 포럼 토픽에 프롬프트가 도착하면 OpenClaw는 승인 프롬프트와 승인 후 후속 조치 모두에서 토픽을 유지합니다.

인라인 승인 버튼도 `channels.telegram.capabilities.inlineButtons`가 대상 표면 (`dm`, `group`, 또는 `all`)을 허용하는지에 따라 달라집니다.

관련 문서: [Exec approvals](/docs/tools/exec-approvals)

- `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`는 네이티브 메뉴에 항목이 너무 많음을 의미합니다. 플러그인/스킬/사용자 정의 명령을 줄이거나 네이티브 메뉴를 비활성화합니다
- 네트워크/fetch 오류로 `setMyCommands failed`는 일반적으로 `api.telegram.org`에 대한 DNS/HTTPS 접근성 문제를 나타냅니다

- Node 22+ + 사용자 정의 fetch/프록시는 AbortSignal 타입 불일치 시 즉시 중단 동작을 트리거할 수 있습니다.
- 일부 호스트는 `api.telegram.org`를 IPv6로 먼저 해석합니다. 깨진 IPv6 이그레스는 간헐적인 Telegram API 실패를 유발할 수 있습니다.
- 로그에 `TypeError: fetch failed` 또는 `Network request for 'getUpdates' failed!`가 포함되면 OpenClaw는 이를 복구 가능한 네트워크 오류로 재시도합니다.
- 직접 이그레스/TLS가 불안정한 VPS 호스트에서는 `channels.telegram.proxy`를 통해 Telegram API 호출을 라우팅합니다:

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

- Node 22+는 `autoSelectFamily=true` (WSL2 제외) 및 `dnsResultOrder=ipv4first`가 기본입니다.
- 호스트가 WSL2이거나 IPv4 전용 동작이 더 잘 작동하는 경우 패밀리 선택을 강제합니다:

channels:
  telegram:
    network:
      autoSelectFamily: false

- 환경 변수 재정의 (임시):
  - `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