Go back

OpenClaw와 텔레그램 연동: 봇 생성부터 그룹 활용까지

Published:  at  08:07 PM

OpenClaw을 설치하고 AI 모델까지 연결했습니다. 이제 뭘 할 수 있을까요? 텔레그램으로 AI와 대화하는 것입니다. PC 앞에 앉아 있지 않아도, 이동 중에 스마트폰으로 AI에게 질문하고 답변을 받을 수 있습니다.

이 글에서는 텔레그램 봇을 만들고 OpenClaw에 연동하는 방법을 단계별로 안내합니다. 그룹 채팅, 포럼 토픽별 에이전트 분리, 외부 서비스 알림 수신까지 실전 활용 예제도 함께 다룹니다.

OpenClaw 설치가 아직 안 되어 있다면 맥에서 OpenClaw 설치 및 설정 가이드를 먼저 참고하세요. AI 모델 선택이 고민이라면 OpenClaw AI 모델 비교 분석도 도움이 됩니다.

왜 텔레그램인가?

OpenClaw은 WhatsApp, Slack, Discord 등 11개 이상의 메시징 채널을 지원합니다. 그중 텔레그램을 추천하는 이유가 있습니다.

사전 준비

시작하기 전에 필요한 것:

항목설명
OpenClaw설치 및 AI 모델 설정 완료
텔레그램 계정스마트폰 또는 데스크톱 앱
5분봇 생성 + 연동 소요 시간

텔레그램 봇 생성

BotFather에게 봇 만들기

텔레그램에서 @BotFather ↗를 검색하고 대화를 시작합니다.

  1. /newbot 명령어를 입력합니다.
  2. 봇 이름을 입력합니다. 한글도 가능합니다. (예: “클로디”)
  3. 봇 유저네임을 입력합니다. 영문+숫자만 가능하며, 반드시 bot으로 끝나야 합니다. (예: fe4all_ai_bot)
  4. BotFather가 API 토큰을 발급합니다.

발급되는 토큰 형식은 다음과 같습니다.

123456789:ABCdefGHIjklMNOpqrsTUVwxyz

보안 주의: 토큰은 비밀번호와 같습니다. 절대 Git에 커밋하지 마세요. .env 파일이나 비밀번호 관리자에 보관하는 것을 권장합니다. 토큰이 유출되었다면 BotFather에서 /revoke로 즉시 재발급하세요.

Privacy Mode 끄기

봇이 그룹 채팅에서 모든 메시지를 볼 수 있도록 Privacy Mode를 꺼야 합니다. 기본값은 ON으로, @봇이름 멘션이 포함된 메시지만 볼 수 있습니다.

  1. BotFather에게 /setprivacy 명령어를 입력합니다.
  2. 생성한 봇을 선택합니다.
  3. Disable을 선택합니다.

Privacy Mode를 변경한 후에는 그룹에서 봇을 제거했다가 다시 추가해야 적용됩니다.

OpenClaw 텔레그램 설정

봇 토큰이 준비되었으면 OpenClaw에 연결합니다. 세 가지 방법이 있습니다.

방법 1: CLI로 채널 추가 (가장 간단)

openclaw channels add --channel telegram --token "123456789:ABCdefGHIjklMNOpqrsTUVwxyz"

한 줄이면 됩니다. Docker 환경이라면 다음과 같이 실행합니다.

docker compose run --rm openclaw-cli channels add --channel telegram --token "<토큰>"

방법 2: 설정 파일 직접 수정 (세밀한 제어)

~/.openclaw/openclaw.json 파일을 열고 channels 섹션에 텔레그램 설정을 추가합니다.

{
  channels: {
    telegram: {
      enabled: true,
      botToken: "123456789:ABCdefGHIjklMNOpqrsTUVwxyz",
      // DM 접근 정책 — 페어링 코드 승인 필요 (가장 안전)
      dmPolicy: "pairing",
      // 그룹 설정 — 멘션 시에만 응답
      groups: {
        "*": { requireMention: true },
      },
    },
  },
}

설정 파일은 JSON5 형식이라 주석과 trailing comma를 지원합니다. 저장하면 즉시 반영됩니다(핫 리로드).

방법 3: 환경변수 (빠른 테스트)

설정 파일 수정 없이 환경변수로 토큰을 전달할 수 있습니다.

export TELEGRAM_BOT_TOKEN="123456789:ABCdefGHIjklMNOpqrsTUVwxyz"
openclaw gateway

빠르게 테스트할 때 유용하지만, 영구 설정은 방법 1이나 2를 사용하세요.

DM 접근 정책

누가 봇에게 DM을 보낼 수 있는지 제어합니다. 기본값은 pairing이며, 가장 안전한 옵션입니다.

정책동작권장 상황
pairing페어링 코드 승인 필요 (기본값)개인 사용
allowlist지정된 사용자만 허용소규모 팀
open모든 사용자 허용공개 서비스 (주의)
disabledDM 차단그룹 전용 봇

open 정책은 스팸 봇 공격에 취약합니다. 개인 사용이라면 pairing을 유지하세요.

연동 테스트

게이트웨이 시작

openclaw gateway

게이트웨이가 실행되면 텔레그램 Long Polling이 자동으로 시작됩니다.

페어링 승인

텔레그램에서 봇에게 아무 메시지를 보냅니다. DM 정책이 pairing이면 페어링 코드가 생성됩니다.

# 페어링 대기 목록 확인
openclaw pairing list telegram

# 페어링 승인
openclaw pairing approve telegram <CODE>

페어링 코드는 1시간 후 만료됩니다. 시간이 지났다면 봇에게 다시 메시지를 보내세요.

연결 상태 확인

openclaw channels status --probe

출력에 다음과 같이 표시되면 성공입니다.

Telegram default: enabled, configured, running, mode:polling

이제 텔레그램에서 봇에게 메시지를 보내면 AI가 답변합니다.

실전 활용 예제

기본 DM 대화를 넘어서 텔레그램 봇을 더 다양하게 활용하는 방법을 알아봅니다.

그룹 채팅 설정

팀원들과 함께 사용하는 그룹에 봇을 추가할 수 있습니다. 그룹 ID를 지정하면 그룹별로 세밀한 설정이 가능합니다.

그룹 ID는 봇을 그룹에 추가한 뒤 메시지를 보내면 OpenClaw 로그에서 확인할 수 있습니다.

# 로그에서 그룹 ID 확인 (chat.id 값)
openclaw logs --follow --filter telegram

로그에 chat.id: -1001234567890 형태로 표시됩니다. 이 값을 설정 파일에 사용합니다.

{
  channels: {
    telegram: {
      groups: {
        "-1001234567890": {
          groupPolicy: "open",
          requireMention: false,
          systemPrompt: "당신은 팀 코딩 어시스턴트입니다. 한국어로 답변하세요.",
        },
      },
    },
  },
}

포럼 토픽별 에이전트 분리

텔레그램 포럼 슈퍼그룹에서는 토픽별로 다른 에이전트 역할을 부여할 수 있습니다. 하나의 그룹에서 용도별 AI를 분리 운영하는 데 유용합니다.

토픽 ID는 텔레그램 데스크톱 앱에서 토픽을 클릭했을 때 URL의 마지막 숫자입니다. (예: https://t.me/c/3595003457/14에서 14가 토픽 ID) OpenClaw 로그의 message_thread_id 값으로도 확인할 수 있습니다.

{
  channels: {
    telegram: {
      groups: {
        "-1003595003457": {
          requireMention: false,
          topics: {
            "14": {
              systemPrompt: "코딩 어시스턴트입니다. 코드 리뷰와 디버깅을 도와줍니다.",
            },
            "27": {
              systemPrompt: "배포/인프라 전문가입니다. CI/CD와 서버 관리를 담당합니다.",
            },
          },
        },
      },
    },
  },
}

토픽 14번에 질문하면 코딩 전문가가, 토픽 27번에 질문하면 인프라 전문가가 답변합니다.

멀티 봇 계정

개인용과 업무용 봇을 분리하여 각각 다른 에이전트에 라우팅할 수 있습니다.

{
  channels: {
    telegram: {
      accounts: [
        {
          name: "personal",
          botToken: "token1...",
          routing: { agent: "main" },
        },
        {
          name: "work",
          botToken: "token2...",
          routing: { agent: "work-agent" },
        },
      ],
    },
  },
}

개인용 봇은 일상적인 질문에, 업무용 봇은 코드 리뷰와 문서 작성에 특화된 시스템 프롬프트를 사용할 수 있습니다.

커스텀 명령어

텔레그램 봇 명령어 메뉴에 표시될 커스텀 명령어를 등록할 수 있습니다.

{
  channels: {
    telegram: {
      commands: { native: "auto" },
      customCommands: [
        { command: "backup", description: "Git 백업 실행" },
        { command: "deploy", description: "배포 트리거" },
        { command: "status", description: "서버 상태 확인" },
      ],
    },
  },
}

텔레그램 채팅에서 /backup을 입력하면 AI 에이전트가 해당 작업을 실행합니다.

외부 서비스 알림 수신 (웹훅)

GitHub, CI/CD 등 외부 서비스에서 OpenClaw 웹훅을 호출하면, 텔레그램으로 알림을 받을 수 있습니다.

먼저 openclaw.json에서 웹훅을 활성화합니다.

{
  hooks: {
    enabled: true,
    token: "your_webhook_secret",
    path: "/hooks",
  },
}

외부 서비스에서 다음과 같이 호출합니다. 웹훅 URL은 {게이트웨이주소}{path}/{엔드포인트} 형식입니다. path는 위에서 설정한 /hooks이고, /agent는 에이전트에게 메시지를 전달하는 내장 엔드포인트입니다.

curl -X POST http://127.0.0.1:18789/hooks/agent \
  -H 'Authorization: Bearer your_webhook_secret' \
  -d '{
    "message": "GitHub에 새 PR이 올라왔습니다: feat/login-page",
    "channel": "telegram",
    "deliver": true
  }'

GitHub Actions나 Jenkins에서 빌드 완료 시 이 웹훅을 호출하도록 설정하면, 텔레그램으로 즉시 알림을 받을 수 있습니다.

보안 체크리스트

2026년 2월 기준, 135,000개 이상의 OpenClaw 인스턴스가 인터넷에 노출되어 있다는 보안 보고가 있었습니다. 텔레그램 봇을 운영할 때 반드시 확인해야 할 보안 항목입니다.

  1. 게이트웨이를 공개 인터넷에 노출하지 마세요. 로컬 네트워크 또는 VPN/Tailnet 뒤에서만 운영하세요.
  2. 봇 토큰을 환경변수로 관리하세요. 설정 파일에 직접 쓰는 대신 "env:TELEGRAM_BOT_TOKEN" 또는 tokenFile 옵션을 사용할 수 있습니다.
  3. DM 정책은 pairing을 유지하세요. open은 스팸 봇 공격에 취약합니다.
  4. ~/.openclaw 디렉토리를 보호하세요. 세션 기록과 자격증명이 포함되어 있습니다.
chmod 700 ~/.openclaw
  1. 웹훅 사용 시 토큰을 반드시 설정하세요. 쿼리스트링 대신 Authorization 헤더로 전달하는 것이 안전합니다.

트러블슈팅

자주 발생하는 문제

증상원인해결책
그룹에서 봇이 응답 안 함Privacy Mode ONBotFather → /setprivacy → OFF → 봇 제거/재추가
특정 그룹만 안 됨화이트리스트 미등록groups에 "*" 또는 해당 그룹 ID 추가
DM 응답 안 함페어링 미완료openclaw pairing list telegram 확인 후 승인
간헐적 타임아웃Node 22 IPv6 문제openclaw.json의 최상위에 network: { autoSelectFamily: false } 추가

디버깅 명령어

문제가 생겼을 때 가장 먼저 실행할 명령어들입니다.

# 실시간 로그 확인
openclaw logs --follow

# 텔레그램 채널만 필터링하여 디버그 로그 확인
openclaw logs --level debug --filter telegram

# 채널 연결 상태 점검
openclaw channels status --probe

# 활성 세션 목록 확인
openclaw sessions list

텔레그램 제한사항

알아두면 유용한 텔레그램 측 제한사항입니다.

항목제한
그룹 메시지 최대 길이4,000자
미디어 최대 크기5MB
그룹 컨텍스트 히스토리기본 50개

마무리

이 글에서 다룬 내용을 정리합니다.

  1. 텔레그램 봇 생성 — BotFather에서 5분이면 완료
  2. OpenClaw 연동 — CLI 한 줄 또는 설정 파일 수정
  3. 페어링 — DM 정책에 따라 안전하게 연결
  4. 실전 활용 — 그룹 채팅, 포럼 토픽, 멀티 봇, 커스텀 명령어, 웹훅 알림
  5. 보안 — 게이트웨이 노출 금지, 토큰 관리, DM 정책 설정

텔레그램은 OpenClaw의 여러 채널 중에서 진입 장벽이 가장 낮고 활용도가 높은 채널입니다. 기본 DM 대화부터 시작해서, 필요에 따라 그룹 봇, 포럼 토픽, 웹훅까지 확장해 보세요.

참고 자료

공식 문서

관련 포스트

참고 가이드

Share this post on:
Share this post via WhatsApp Share this post on Facebook Share this post on X Share this post via Telegram Share this post on Pinterest Share this post via email
Previous Post
OpenClaw AI 모델 비교 분석: 가격, 성능, 비용 절감 전략 총정리