Telegram 채널 설정

OpenClaw와 Telegram을 연동하여 AI 어시스턴트를 구축하는 방법을 안내합니다.

기준일: 2026-06-07
공식 기준: Telegram, Pairing, Access groups

개요

Telegram 채널이란?

OpenClaw의 Telegram 채널은 Telegram Bot API를 통해 사용자와 AI가 대화하는 방식입니다:

• @BotFather로 생성한 봇 토큰 사용
• 개인 채팅, 그룹 채팅, 채널 모두 지원
• Telegram Web, 모바일 앱 모두 지원

1단계: Telegram 봇 생성

BotFather에서 봇 생성

1. Telegram에서 @BotFather 검색 및 시작
2. /newbot 명령어 입력
3. 봇의 표시 이름 입력 (예: My AI Assistant)
4. 봇의 사용자명 입력 (반드시 bot으로 끝나야 함, 예: my_ai_assistant_bot)
5. 발급된 Bot Token 복사

BotFather: Done! Congratulations on your new bot.
You will find it at t.me/my_ai_assistant_bot.
You can now add a description...

Use this token to access the HTTP API:
123456789:ABCdefGHIjklMNOpqrsTUVwxyz

봇 추가 설정 (선택사항)

# 봇 설명 추가
/setdescription

# 봇 프로필 사진 설정
/setuserpic

# 봇 명령어 목록 설정
/setcommands

2단계: OpenClaw 설정

CLI로 설정

# Telegram 채널 활성화
openclaw config set channels.telegram.enabled true

# 봇 토큰 설정
openclaw config set channels.telegram.botToken "123456789:ABCdefGHIjklMNOpqrsTUVwxyz"

설정 파일로 직접 설정

{
  "channels": {
    "telegram": {
      "enabled": true,
      "botToken": "123456789:ABCdefGHIjklMNOpqrsTUVwxyz",
      "tokenFile": "~/.openclaw/secrets/telegram-bot-token",
      "defaultAccount": "default",
      "accounts": {
        "default": {}
      },
      "dmPolicy": "pairing",
      "groups": {
        "*": {
          "requireMention": true
        }
      }
    }
  }
}

botToken은 빠른 로컬 확인에 편합니다. 운영에서는 tokenFile, 환경 변수 fallback인 TELEGRAM_BOT_TOKEN, 또는 SecretRef 지원 경로를 검토하고, 2개 이상 계정이 있으면 defaultAccount 또는 accounts.default를 명시합니다.

보안 설정 (특정 사용자만 허용)

{
  "channels": {
    "telegram": {
      "enabled": true,
      "botToken": "YOUR_BOT_TOKEN",
      "dmPolicy": "allowlist",
      "allowFrom": [123456789, 987654321],
      "groups": {
        "-1001234567890": {
          "requireMention": true,
          "groupAllowFrom": [123456789]
        }
      }
    }
  }
}

채팅 ID 확인 방법:

# 봇에 메시지 보낸 후 로그에서 확인
openclaw logs | grep "chat_id"

3단계: AI 모델 설정

# 모델 목록과 인증 상태 확인
openclaw models list
openclaw model auth status

# 기본 모델 변경은 모델 CLI 또는 agents.defaults.model.primary 경로를 사용
openclaw models set anthropic/claude-sonnet-4-6
openclaw config set agents.defaults.model.primary "anthropic/claude-sonnet-4-6"

4단계: Gateway 시작 및 테스트

# Gateway 시작
openclaw gateway start

# 연결 테스트
openclaw channels status --probe

# 로그 확인
openclaw logs --follow

5단계: Telegram에서 테스트

1. Telegram에서 본인의 봇 검색 (예: @my_ai_assistant_bot)
2. START 버튼 클릭 또는 /start 입력
3. 메시지 입력 후 AI 응답 확인

사용자: 안녕!
봇: 안녕하세요! 저는 OpenClaw AI 어시스턴트입니다.
    무엇을 도와드릴까요?

사용자: 파이썬으로 Hello World를 출력하는 코드를 알려줘
봇: 파이썬으로 Hello World를 출력하는 코드입니다:

    ```python
    print("Hello, World!")
    ```

고급 설정

그룹 채팅 지원

{
  "channels": {
    "telegram": {
      "enabled": true,
      "botToken": "YOUR_BOT_TOKEN",
      "dmPolicy": "pairing",
      "groups": {
        "-1001234567890": {
          "requireMention": true,
          "groupAllowFrom": [123456789]
        }
      }
    }
  }
}

Custom commands

{
  "channels": {
    "telegram": {
      "customCommands": [
        { "command": "backup", "description": "Git backup" },
        { "command": "generate", "description": "Create an image" }
      ],
      "replyToMode": "first",
      "linkPreview": true,
      "apiRoot": "https://api.telegram.org",
      "streaming": "partial",
      "retry": {
        "attempts": 3,
        "minDelayMs": 400,
        "maxDelayMs": 30000,
        "jitter": 0.1
      }
    }
  }
}

apiRoot에는 Bot token이 붙은 URL이 아니라 Telegram Bot API root만 넣습니다. 직접 호스팅한 Bot API proxy를 쓰는 경우에도 같은 규칙을 유지합니다.

파일 전송 설정

{
  "channels": {
    "telegram": {
      "files": {
        "allowReceive": true,
        "maxFileSize": 20971520,
        "allowedTypes": ["document", "photo", "audio"]
      }
    }
  }
}

트러블슈팅

"Unauthorized" 오류

# 봇 토큰 재확인
openclaw config get channels.telegram.botToken

# 봇 토큰 재설정
openclaw config set channels.telegram.botToken "NEW_TOKEN"
openclaw gateway restart

봇이 그룹에서 응답하지 않음

그룹에서 봇 관리자 권한 확인:

1. 그룹 설정 → 관리자 → 봇 선택
2. 메시지 읽기/쓰기 권한 확인

메시지 수신 지연

Telegram은 long polling을 기본으로 사용합니다. 지연이 보이면 토큰, gateway 로그, BotFather의 privacy mode, 그룹 ID 위치(channels.telegram.groups)를 먼저 확인합니다.

최신 Telegram 업데이트

폴링 감시 임계값 설정 (v2026.4.20)

v2026.4.20부터 Telegram 폴링 감시 임계값 기본값이 90초에서 120초로 상향되었습니다. 장시간 실행되는 Telegram 작업에서 폴링이 중단(stalled)으로 오인되는 경우를 줄입니다 (#57737).

계정별 또는 전역으로 임계값을 조정할 수 있습니다:

{
  "channels": {
    "telegram": {
      "pollingStallThresholdMs": 120000
    }
  }
}

계정별 설정도 동일한 키로 지원됩니다.

참고:

• 공식 Telegram Bot API 문서
• BotFather 사용법