> ## Documentation Index
> Fetch the complete documentation index at: https://oc-guide.openclaw-korea.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Telegram

> Telegram 봇으로 AI와 대화하기

Telegram은 OpenClaw에서 **가장 권장하는 메시징 채널**입니다.
봇 API가 강력하고, 설정이 간단하며, 파일/이미지/음성을 모두 지원합니다.

## 왜 Telegram인가?

<CardGroup cols={3}>
  <Card title="🚀 쉬운 설정" icon="rocket">
    BotFather로 5분 만에 봇 생성
  </Card>

  <Card title="📎 풍부한 미디어" icon="paperclip">
    사진, 파일, 음성, 영상 모두 지원
  </Card>

  <Card title="🔒 개인 채팅" icon="lock">
    1:1 비공개 대화 기본 제공
  </Card>
</CardGroup>

## 봇 생성

<Steps>
  <Step title="BotFather 접속">
    Telegram에서 [@BotFather](https://t.me/BotFather)를 검색하여 대화를 시작합니다.
  </Step>

  <Step title="새 봇 생성">
    ```
    /newbot
    ```

    봇 이름과 username을 입력합니다.
    username은 반드시 `bot`으로 끝나야 합니다 (예: `my_claw_bot`).
  </Step>

  <Step title="토큰 복사">
    BotFather가 발급한 토큰을 복사합니다:

    ```
    Use this token to access the HTTP API:
    123456789:ABCdefGHIjklMNOpqrsTUVwxyz
    ```
  </Step>

  <Step title="OpenClaw에 설정">
    ```bash theme={null}
    openclaw config set telegram.token "YOUR_BOT_TOKEN"
    openclaw gateway restart
    ```
  </Step>

  <Step title="첫 메시지">
    봇에게 DM을 보내면 AI가 응답합니다!
  </Step>
</Steps>

## 봇 커스터마이징

BotFather에서 추가 설정:

```
/setdescription - 봇 설명
/setabouttext - 봇 소개
/setuserpic - 프로필 사진
/setcommands - 명령어 메뉴
```

## 주요 기능

### 텍스트 대화

일반 메시지를 보내면 AI가 응답합니다.

### 이미지 분석

사진을 보내면 AI가 분석합니다:

```
[사진 전송]
AI: "맑은 날 한강 공원 사진이네요. 산책하기 좋은 날씨 같아요!"
```

### 음성 메시지

음성 메시지를 보내면 AI가 텍스트로 변환 후 응답합니다.
TTS 스킬이 있으면 음성으로 답할 수도 있습니다.

### 파일 공유

문서, 코드 파일 등을 보내면 AI가 내용을 분석합니다.

## 그룹 채팅

Telegram 그룹에 봇을 추가할 수 있습니다:

```bash theme={null}
# 그룹 설정
openclaw config set telegram.groups.allowed "[-100123456789]"
```

<Warning>
  그룹에서는 봇이 모든 메시지를 받을 수 있습니다.
  AGENTS.md의 그룹 채팅 규칙에 따라 AI가 언제 응답할지 판단합니다.
</Warning>

## 알림 전송

크론잡이나 하트비트에서 Telegram으로 알림을 보냅니다:

```bash theme={null}
# 크론잡에서 Telegram으로 결과 전송
openclaw cron add --name "alert" \
  --every "1h" \
  --message "서버 상태 체크" \
  --announce --channel last
```

AI 도구로 직접 메시지 전송:

```
message.send(
  action="send",
  message="회의 10분 전입니다!",
  target="telegram:123456789"
)
```

## 리액션

Telegram에서 AI가 이모지 리액션을 사용할 수 있습니다:

```
message.react(
  action="react",
  messageId="12345",
  emoji="👍"
)
```

<Tip>
  리액션은 가볍게 "봤어"를 표현하는 좋은 방법입니다.
  AGENTS.md에서 리액션 모드(MINIMAL/NORMAL)를 설정할 수 있습니다.
</Tip>

## 문제 해결

| 증상                | 해결                           |
| ----------------- | ---------------------------- |
| 봇이 응답 안 함         | `openclaw gateway status` 확인 |
| "Unauthorized" 에러 | 토큰이 올바른지 확인                  |
| 그룹에서 메시지 못 받음     | BotFather에서 Privacy Mode 해제  |
| 파일 전송 실패          | 파일 크기 제한 (50MB) 확인           |