OpenClaw

OpenClaw Telegram 채널

메시징
쉬움

grammY Bot API 프레임워크를 사용하여 OpenClaw를 Telegram에 연결합니다. @BotFather를 통해 Telegram 봇을 만들고 토큰을 받으면 몇 분 안에 AI 어시스턴트가 Telegram에서 작동합니다. 기본적으로 롱 폴링을 사용하며 선택적으로 Webhook 모드를 사용할 수 있습니다. 가장 쉽게 설정할 수 있는 채널 중 하나로, 인라인 버튼, 스티커, 리액션, 그룹 채팅 등 풍부한 기능을 지원합니다.

기본 정보
난이도쉬움
카테고리메시징
지원 기능 수6 / 6

Telegram 지원 기능

텍스트 메시지

지원

미디어 및 파일

지원

리액션

지원

스레드

지원

음성 메시지

지원

그룹 채팅

지원

Telegram 사전 요구사항

  • Telegram 계정
  • @BotFather에서 받은 Bot Token (@BotFather에게 /newbot 전송)
  • OpenClaw Gateway 실행 및 구성 완료
  • 서버에 Node.js 18+ 설치

Telegram 빠른 설정

1

@BotFather로 봇 생성

Telegram을 열고 @BotFather를 검색한 후 /newbot을 전송합니다. 안내에 따라 봇 이름을 지정하고 API 토큰을 받습니다. 이 토큰을 안전하게 보관하세요 — 설정 시 필요합니다.

2

Telegram 채널 구성 추가

~/.openclaw/openclaw.json에 Telegram 채널 구성을 추가합니다. @BotFather에서 받은 봇 토큰을 botToken 필드에 붙여넣습니다. dmPolicy(pairing, allowlist 또는 open)를 설정하여 AI 어시스턴트와 대화할 수 있는 사용자를 제어합니다.

3

Gateway 시작 및 테스트

Gateway 프로세스를 시작합니다. Telegram에서 봇을 검색하고 메시지를 보냅니다. 기본 pairing 정책을 사용하는 경우 'openclaw pairing approve telegram <code>'로 발신자를 승인합니다. OpenClaw가 AI 어시스턴트를 통해 응답해야 합니다.

Telegram 구성 예시

config.json
{
  "channels": {
    "telegram": {
      "enabled": true,
      "botToken": "YOUR_BOT_TOKEN_FROM_BOTFATHER",
      "dmPolicy": "pairing"
    }
  }
}

Telegram 상세 문서

아키텍처 개요

OpenClaw는 grammY 프레임워크를 통해 Telegram에 연결됩니다 — 모던하고 TypeScript 우선의 Telegram Bot API 라이브러리입니다. 봇은 기본적으로 롱 폴링을 사용하여 Telegram 서버에 주기적으로 새 업데이트를 요청합니다. 추가 설정 없이 바로 작동합니다. 프로덕션 배포를 위해 Webhook 모드로 전환할 수도 있습니다. Webhook 모드에서는 Telegram이 서버 엔드포인트로 직접 업데이트를 푸시하여 더 효율적이고 지연 시간이 줄어듭니다.
롱 폴링은 NAT 및 방화벽 뒤에서도 설정 없이 작동합니다. Webhook 모드는 공개적으로 접근 가능한 HTTPS 엔드포인트가 필요합니다.
봇 토큰은 TELEGRAM_BOT_TOKEN 환경 변수 또는 설정 파일의 channels.telegram.botToken 필드에 저장할 수 있습니다.

@BotFather로 봇 만들기

BotFather는 Telegram 공식 봇 생성 및 관리 도구입니다. 단계: 1. Telegram을 열고 @BotFather 검색 2. /newbot을 전송하여 생성 프로세스 시작 3. 표시 이름 선택 (예: "나의 AI 어시스턴트") 4. 'bot'으로 끝나는 사용자 이름 선택 (예: "my_ai_assistant_bot") 5. BotFather가 API 토큰을 반환 — 안전하게 보관 생성 후 BotFather 명령으로 추가 커스터마이징: • /setdescription — 프로필 설명 설정 • /setabouttext — '정보' 섹션 텍스트 설정 • /setuserpic — 프로필 사진 업로드 • /setprivacy — 그룹 메시지 프라이버시 모드 전환
봇 토큰을 비밀로 유지하세요. 토큰을 가진 사람은 누구나 봇을 제어할 수 있습니다. 유출된 경우 BotFather에서 /revoke로 새 토큰을 생성하세요.

DM 정책

DM(다이렉트 메시지) 정책은 AI 어시스턴트와 개인 채팅할 수 있는 사용자를 제어합니다. OpenClaw는 세 가지 정책을 지원합니다: • pairing (기본값) — 새 사용자는 페어링 플로우를 거쳐야 합니다. 메시지를 보내면 페어링 코드(1시간 유효)를 받고, CLI에서 승인 또는 거부합니다. • allowlist — allowFrom 목록에 명시된 숫자 사용자 ID만 봇에 메시지를 보낼 수 있습니다. 나머지는 무시됩니다. • open — 봇에게 메시지를 보내는 모든 사람이 응답을 받습니다. 프로덕션에서는 주의해서 사용하세요.
openclaw.json
{
  "channels": {
    "telegram": {
      "dmPolicy": "pairing",
      "allowFrom": [123456789, 987654321]
    }
  }
}
사용자의 Telegram 숫자 ID를 찾으려면 @userinfobot을 사용하거나 메시지 전송 시 Gateway 로그를 확인하세요.

그룹 채팅 관리

OpenClaw는 Telegram 그룹 채팅을 지원하며 두 가지 독립적인 메커니즘으로 유연한 접근 제어를 제공합니다: 1. 그룹 허용 목록 — 모든 그룹 또는 channels.telegram.groups에 나열된 그룹만. 2. 그룹 정책 — 발신자 권한 제어: • open — 모든 그룹 멤버가 봇을 트리거할 수 있음 • allowlist — 승인된 발신자만 상호작용 가능 • disabled — 그룹 메시지 완전 무시 기본적으로 봇은 그룹에서 @멘션이 필요합니다. 이 동작을 변경할 수 있습니다: • /activation always 명령 (세션 한정) • 설정에서 requireMention: false로 영구 적용
openclaw.json
{
  "channels": {
    "telegram": {
      "groupPolicy": "open",
      "requireMention": false,
      "groups": ["-1001234567890"]
    }
  }
}
포럼 스타일 그룹(토픽)의 경우, OpenClaw는 스레드 ID로 각 토픽을 격리하고 토픽별 설정 오버라이드를 적용할 수 있습니다.
봇이 관리자가 아닌 상태에서 모든 그룹 메시지를 보려면 BotFather에서 /setprivacy로 프라이버시 모드를 비활성화한 후, 봇을 그룹에서 제거하고 다시 추가해야 합니다.

메시지 포맷 및 스트리밍

OpenClaw는 다양한 메시지 포맷팅 및 전달 옵션을 제공합니다: 포맷팅: 발신 텍스트는 Telegram의 HTML 파서를 사용하며 Markdown 스타일에서 자동 변환됩니다. HTML 파싱 실패 시 일반 텍스트로 재시도됩니다. 스트리밍: 드래프트 버블은 DM에서 부분 응답 스트리밍을 지원합니다. 두 가지 모드: • partial (기본값) — AI 생성 시 단일 메시지를 점진적으로 업데이트 • block — 완전한 블록으로 청크 업데이트 전송 텍스트는 기본적으로 4,000자로 분할됩니다 (Telegram 제한). chunkMode: "newline"을 활성화하면 문단 경계로 분할됩니다.
openclaw.json
{
  "channels": {
    "telegram": {
      "streamMode": "partial",
      "chunkMode": "newline"
    }
  }
}

인라인 버튼

OpenClaw는 Telegram의 대화형 인라인 키보드 버튼을 지원합니다. 활성화하면 AI가 메시지 아래에 버튼을 표시할 수 있습니다. 버튼 클릭 시 콜백 데이터가 에이전트에게 전송됩니다. 사용 가능한 모드: • off — 버튼 비활성화 (기본값) • dm — 개인 채팅에서만 활성화 • group — 그룹 채팅에서만 활성화 • all — 모든 곳에서 활성화 • allowlist — 발신자 인증으로 제한
openclaw.json
{
  "channels": {
    "telegram": {
      "capabilities": {
        "inlineButtons": "all"
      }
    }
  }
}

스티커 및 미디어

OpenClaw는 Telegram 스티커와 미디어 파일을 처리합니다: 스티커: 정적 스티커는 다운로드되어 비전 분석으로 처리됩니다. 설명은 캐시되어 반복 API 호출을 방지합니다. 애니메이션 및 비디오 스티커는 처리를 건너뜁니다. 에이전트는 저장된 파일 ID로 스티커를 보내고 설명, 이모지 또는 세트 이름으로 캐시된 스티커를 검색할 수 있습니다. 미디어: 기본 미디어 업로드/다운로드 제한은 5 MB입니다. 봇은 이미지, 문서, 오디오 파일, 비디오의 송수신을 지원합니다.
에이전트 설정에서 sticker 액션을 활성화하면 파일 ID 또는 캐시 검색으로 스티커를 보낼 수 있습니다.

리액션

OpenClaw는 Telegram의 리액션 시스템을 지원하며 이모지 리액션의 수신과 전송 모두 가능합니다: 수신된 리액션은 시스템 이벤트를 생성하여 에이전트 컨텍스트에 추가됩니다: • off — 알림 없음 • own — 봇 메시지에 대한 리액션만 • all — 채팅의 모든 리액션 봇 리액션 수준: • off — 리액션 없음 • ack — 처리 중 확인 리액션 (기본값) • minimal — 기본 리액션 • extensive — 전체 이모지 범위
openclaw.json
{
  "channels": {
    "telegram": {
      "reactionNotifications": "own",
      "reactionLevel": "ack"
    }
  }
}

명령 및 도구

네이티브 봇 명령(/status, /reset 등)은 Telegram의 봇 명령 메뉴에 자동 등록되어 사용자가 쉽게 찾을 수 있습니다. 커스텀 명령은 설정으로 추가할 수 있지만 메뉴 항목으로만 작동합니다. 에이전트는 도구 액션도 지원합니다: • 특정 채팅에 메시지 전송 • 이모지로 리액션 • 메시지 삭제 • [[reply_to:<id>]] 태그로 특정 메시지에 답장
에이전트 응답에 [[reply_to_current]]를 사용하면 사용자의 현재 메시지에 직접 답장할 수 있습니다.
응답에 [[audio_as_voice]]를 포함하거나 도구 호출에서 asVoice: true를 설정하면 음성 노트 형식을 강제할 수 있습니다.

Webhook 모드

프로덕션 배포에는 롱 폴링보다 Webhook 모드가 권장됩니다. Telegram이 서버로 직접 업데이트를 푸시하여 지연 시간과 리소스 사용량을 줄입니다. 설정에서 webhookUrl과 webhookSecret을 설정합니다. 로컬 엔드포인트는 기본적으로 0.0.0.0:8787에 바인딩됩니다.
openclaw.json
{
  "channels": {
    "telegram": {
      "webhookUrl": "https://your-domain.com/telegram/webhook",
      "webhookSecret": "your-random-secret-string"
    }
  }
}
폴링에서 Webhook 모드로 전환하면 Gateway가 시작 시 자동으로 Telegram에 Webhook URL을 등록합니다.
Webhook 모드는 공개적으로 접근 가능한 HTTPS 엔드포인트가 필요합니다. 서버에 유효한 SSL 인증서가 있는지 확인하세요.

Telegram 구성 참조

enabled
Type: booleanDefault: true

Telegram 채널 활성화 또는 비활성화

botToken
Type: stringDefault: ""

@BotFather의 Telegram Bot API 토큰. TELEGRAM_BOT_TOKEN 환경 변수도 지원

dmPolicy
Type: stringDefault: "pairing"

DM 접근 제어. 옵션: pairing, allowlist, open

allowFrom
Type: number[]Default: []

허용된 Telegram 사용자 ID (dmPolicy가 allowlist일 때)

groupPolicy
Type: stringDefault: "disabled"

그룹 채팅 정책. 옵션: disabled, open, allowlist

groups
Type: string[]Default: []

허용된 그룹 채팅 ID 목록

requireMention
Type: booleanDefault: true

그룹에서 @멘션 필요 여부

streamMode
Type: stringDefault: "partial"

스트리밍 모드. 옵션: partial, block

chunkMode
Type: stringDefault: "split"

긴 응답 처리. 옵션: split, newline

webhookUrl
Type: stringDefault: ""

Webhook 모드용 HTTPS URL

webhookSecret
Type: stringDefault: ""

Webhook 검증용 비밀 토큰

reactionNotifications
Type: stringDefault: "off"

리액션 알림. 옵션: off, own, all

reactionLevel
Type: stringDefault: "ack"

봇 리액션 기능. 옵션: off, ack, minimal, extensive

capabilities.inlineButtons
Type: stringDefault: "off"

인라인 버튼 모드. 옵션: off, dm, group, all, allowlist

configWrites
Type: booleanDefault: true

슈퍼그룹 업그레이드 시 채팅 ID 자동 마이그레이션

Telegram 자주 묻는 질문

Telegram 문제 해결

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

프라이버시 모드가 기본적으로 활성화되어 있습니다. 봇은 @멘션과 슬래시 명령만 수신합니다.

BotFather에서 프라이버시 모드 비활성화: /setprivacy → Disable. 봇을 그룹에서 제거하고 다시 추가. OpenClaw 설정에서 requireMention: false 설정.
봇이 어떤 메시지에도 응답하지 않음

잘못된 토큰, Gateway 미실행 또는 네트워크 문제.

토큰 확인: curl https://api.telegram.org/bot<token>/getMe. Gateway 로그 확인. IPv6 문제 시 api.telegram.org에 IPv4 해석 강제.
Webhook이 업데이트를 수신하지 않음

Webhook URL 접근 불가, SSL 인증서 무효 또는 Webhook 미등록.

URL 접근성 확인(curl). SSL 인증서 유효성 확인. 상태 확인: curl https://api.telegram.org/bot<token>/getWebhookInfo. Gateway 재시작.
메시지가 잘리거나 잘못 분할됨

Telegram은 4,096자 메시지 제한이 있습니다. 긴 AI 응답은 자동으로 청크됩니다.

chunkMode를 'newline'으로 설정하여 문자 제한 대신 문단 경계로 분할합니다.
전체 문서 보기모든 채널로 돌아가기

관련 채널

WhatsApp

Medium

OpenClaw Baileys 프로토콜을 사용한 QR 코드 연결

설정 가이드

Discord

Easy

OpenClaw discord.js를 사용한 Bot Token 통합

설정 가이드

Signal

Hard

OpenClaw signal-cli를 통한 프라이버시 중심 연결

설정 가이드