OpenClaw 텔레그램 봇 연동 완벽 가이드: 나만의 AI 비서를 메신저로 만나기

작성일자 글쓴이

스마트폰으로 카톡하듯 나만의 AI 비서에게 언제 어디서든 명령을 내릴 수 있다면 어떨까요? 🤖 오늘은 요즘 가장 핫한 오픈소스 AI 에이전트 OpenClaw(오픈클로)를 텔레그램과 연동하는 방법을 완벽하게 정리해 드리겠습니다! 이 글을 따라하시면 여러분도 10분 안에 나만의 AI 비서를 텔레그램에서 만날 수 있어요.

🦞 OpenClaw란 무엇인가요?

OpenClaw는 원래 Clawdbot, Moltbot이라는 이름으로 시작된 오픈소스 AI 에이전트 프로젝트입니다. 2025년 말부터 2026년 초까지 여러 번의 리브랜딩을 거쳐 현재 ‘OpenClaw’라는 공식 명칭으로 확정되었어요. 이름의 유래는 재미있게도 ‘바닷가재(Lobster)’의 집게발(Claw)에서 왔답니다! 🦞

OpenClaw의 가장 큰 장점은 다양한 메신저 채널을 동시에 지원한다는 점이에요. 텔레그램, 디스코드, 슬랙, 왓츠앱, 시그널, 심지어 아이메시지까지! 여러 채널을 동시에 활성화해도 OpenClaw가 각 대화를 알아서 라우팅해 줍니다. 공식 철학은 이렇습니다: “Channels can run simultaneously; configure multiple and OpenClaw will route per chat” – 즉, 여러 채널을 동시에 설정해두면 각 채팅별로 적절히 라우팅해준다는 뜻이에요.

또한 OpenClaw는 자체 AI 모델이 아니라 Claude, GPT-4, Gemini 같은 기존 AI를 연결해 주는 ‘플랫폼’ 역할을 합니다. 그래서 연결하는 모델(Claude 3.5나 GPT-4o 등)이 한국어를 잘하면 OpenClaw도 완벽하게 한국어로 소통할 수 있어요. 별도의 한국어 버전이 필요 없는 이유죠!

📱 왜 텔레그램 연동이 가장 추천될까요?

OpenClaw가 지원하는 수많은 채널 중에서 텔레그램이 초보자에게 가장 추천되는 이유가 있어요. 각 채널별 특징을 표로 정리해 볼게요:

채널 난이도 요구사항 특징
Telegram 쉬움 Bot Token 가장 빠른 설정, 그룹 지원
Discord 쉬움 Bot Token + Intents 서버/채널별 격리, 슬래시 명령
Slack 보통 App Token + Bot Token 업무용 최적, 스레드 지원
WhatsApp 복잡 QR 페어링 + 전화번호 별도 번호 권장
Signal 보통 signal-cli + Java 보안 중시, 별도 번호 권장
iMessage 복잡 macOS + imsg CLI Apple 생태계 전용

텔레그램이 추천되는 구체적인 이유는 다음과 같아요:

  • 설정이 가장 간단해요 – 단 5분이면 연동 완료! 별도의 서버 설정 없이 봇 토큰만 있으면 됩니다.
  • 봇 API가 무료예요 – 텔레그램 봇 API는 완전 무료로 제공됩니다. 별도의 비용이 들지 않아요.
  • 문서화가 잘 되어 있어요 – 공식 문서와 커뮤니티 자료가 풍부해서 문제가 생겨도 쉽게 해결할 수 있습니다.
  • 그룹 채팅 지원 – 여러 사람과 함께 AI 비서를 사용할 수 있어요. 가족이나 팀과 함께 활용하기 좋습니다.
  • 안정적인 연결 – 다른 채널에 비해 연결이 끊기는 일이 적고, 웹훅 모드도 지원합니다.
  • 크로스 플랫폼 – iOS, Android, Windows, Mac, Linux, 웹 등 모든 플랫폼에서 동일하게 사용 가능해요.

반면 왓츠앱은 QR 페어링이 필요하고 별도 전화번호가 권장되며, 시그널은 Java 설치가 필요하고, 아이메시지는 macOS에서만 동작해요. 첫 채널 연동은 텔레그램으로 시작하는 것을 강력히 추천드립니다! 💪

🛠️ 사전 준비사항

텔레그램 연동을 시작하기 전에 다음 항목들이 준비되어 있어야 해요. 하나씩 체크해 볼까요?

1. OpenClaw 설치 및 AI 모델 연결

OpenClaw가 아직 설치되지 않았다면 먼저 설치를 진행해야 해요. Node.js 22 이상이 필요하며, 다음 명령어로 간단히 설치할 수 있습니다:

# Node.js 버전 확인 (22 이상 필요)
node --version

# OpenClaw 설치
npm install -g openclaw@latest

# 초기 설정 시작
openclaw onboard

설치 과정에서 Claude, GPT-4, Gemini 등 원하는 AI 모델의 API 키를 입력하게 됩니다. Google Gemini의 경우 무료 API 키를 제공하고 있어서 비용 부담 없이 시작할 수 있어요! Anthropic의 Claude나 OpenAI의 GPT-4를 사용하려면 해당 서비스의 API 키가 필요합니다.

2. 텔레그램 앱 설치

스마트폰이나 PC에 텔레그램 앱이 설치되어 있어야 합니다. 텔레그램은 공식 웹사이트(telegram.org)에서 다운로드할 수 있어요. 한국에서는 최근 SMS 인증 비용 문제로 2,000원의 비용이 발생할 수 있으니 참고해 주세요. 이미 텔레그램 계정이 있다면 이 단계는 건너뛰셔도 됩니다.

🤖 텔레그램 봇 생성하기

이제 본격적으로 텔레그램 봇을 만들어 볼게요! 텔레그램에서 봇은 @BotFather라는 공식 봇을 통해 생성합니다. BotFather는 별도의 웹 관리자 페이지가 아니라, 텔레그램 앱 안에서 직접 대화하는 공식 봇이에요. 일반 친구에게 메시지 보내듯이 BotFather에게 명령어를 채팅으로 보내면 됩니다.

Step 1: BotFather 찾기

텔레그램 앱을 열고 상단 검색창에 @BotFather를 검색한 후 채팅을 시작하세요. 파란색 체크 표시가 있는 공식 계정을 선택해야 해요! 가짜 BotFather를 조심하세요.

Step 2: 새 봇 생성

BotFather와의 채팅창에서 /newbot 명령어를 입력하고 전송하세요. 그러면 BotFather가 몇 가지 질문을 할 거예요:

  • 봇 이름 (Name): 자유롭게 입력 가능해요. 한글도 됩니다! 예: “My AI Assistant”, “나의 AI 비서”
  • 봇 사용자명 (Username): 반드시 bot으로 끝나야 해요. 영문, 숫자, 밑줄만 사용 가능합니다. 예: “my_ai_assistant_bot”

실제 대화 예시를 보여드릴게요:

# 내가 보내는 메시지
/newbot

# BotFather 응답:
"Alright, a new bot. How are we going to call it?
Please choose a name for your bot."

# 내가 보내는 메시지 (봇 표시 이름)
My AI Assistant

# BotFather 응답:
"Good. Now let's choose a username for your bot.
It must end in 'bot'. Like this, for example: TetrisBot"

# 내가 보내는 메시지 (고유 username)
my_ai_assistant_bot

# BotFather 응답:
"Done! Congratulations on your new bot."
Use this token to access the HTTP API:
1234567890:ABCdefGhIJKlmnOPQrstUVwxyz ← 이게 토큰!

Step 3: 토큰 저장

봇 생성이 완료되면 BotFather가 API 토큰을 발급해 줍니다. 이 토큰은 1234567890:ABCdefGhIJKlmnOPQrstUVwxyz 형식이에요. 이 토큰은 메모장이나 안전한 곳에 복사해 두세요!

⚠️ 보안 주의: 발급받은 토큰은 절대 공개하면 안 됩니다! 토큰이 있으면 누구나 봇을 조작할 수 있거든요. 실수로 노출했다면 BotFather에서 /revoke 명령으로 즉시 토큰을 재발급받으세요. 🔐

⚙️ OpenClaw 설정하기

이제 발급받은 텔레그램 봇 토큰을 OpenClaw에 연결할 차례예요! 세 가지 방법 중 편한 것을 선택하시면 됩니다.

방법 1: onboard 명령어 사용 (권장)

가장 쉬운 방법은 onboard 명령어를 사용하는 거예요. 대화형으로 설정을 진행할 수 있어서 초보자분들께 추천드립니다:

# 현재 실행 중인 게이트웨이 중지
openclaw gateway stop

# 재설정 시작
openclaw onboard

설정 과정에서 “Config handling”에서 “Update values”를 선택하고, 채널에서 “Telegram (Bot API)”를 선택한 후 아까 복사해둔 봇 토큰을 붙여넣으면 됩니다! 토큰 형식은 8711xxxxx:AAHH... 이런 형식이에요.

방법 2: 환경변수 직접 설정

수동으로 설정하고 싶다면 환경변수 파일을 직접 수정할 수도 있어요. 터미널에서 다음 명령어를 실행하세요:

# ~/.openclaw/.env 파일에 추가
echo "TELEGRAM_BOT_TOKEN=1234567890:ABCdefGhIJKlmnOPQrstUVwxyz" >> ~/.openclaw/.env

# AI 모델 키도 함께 설정 (택 1)
# Anthropic Claude 사용 시
echo "ANTHROPIC_API_KEY=sk-ant-api03-xxxxxxxx" >> ~/.openclaw/.env

# Google Gemini 사용 시
echo "GOOGLE_GENERATIVE_AI_API_KEY=AIzaSyDxxxxxxxxx" >> ~/.openclaw/.env

# OpenAI GPT 사용 시
echo "OPENAI_API_KEY=sk-proj-xxxxxxxxx" >> ~/.openclaw/.env

방법 3: JSON 설정 파일 수정

JSON 설정 파일을 직접 수정할 수도 있습니다. 더 세밀한 설정이 필요할 때 유용해요:

// ~/.openclaw/openclaw.json
{
  "channels": {
    "telegram": {
      "enabled": true,
      "botToken": "1234567890:ABCdefGhIJKlmnOPQrstUVwxyz",
      // 그룹에서 멘션 없이도 응답 (선택)
      "groups": {
        "*": { "requireMention": false }
      },
      // 응답 스트리밍 모드 (선택)
      "streamMode": "partial",
      // 리액션 알림 (선택)
      "reactionNotifications": true
    }
  }
}

🔗 페어링 (Pairing) 진행하기

설정이 완료되면 OpenClaw와 텔레그램 봇을 연결하는 페어링 과정이 필요해요. 이건 보안을 위한 중요한 단계입니다! 아무나 여러분의 AI 비서에 접근하지 못하도록 승인된 사용자만 사용할 수 있게 해줍니다.

Step 1: 게이트웨이 시작/재시작

# 게이트웨이 재시작
openclaw gateway restart

# 상태 확인
openclaw status --all
# Telegram 채널이 "connected"로 표시되면 성공!

Step 2: 텔레그램 봇과 대화 시작

텔레그램 앱에서 방금 만든 봇을 찾아 /start 명령어를 보내세요. 봇이 아직 페어링되지 않았기 때문에 페어링 코드가 포함된 안내 메시지를 보내줄 거예요. 이 코드를 메모해 두세요!

Step 3: 페어링 승인

⚠️ 중요: 아래 명령어는 텔레그램 채팅방이 아닌, 컴퓨터의 터미널(Terminal) 창에 입력해야 합니다!

# 페어링 요청 목록 확인
openclaw pairing list telegram

# 페어링 승인 (코드는 텔레그램에서 확인한 것 입력)
# 예: 코드가 123456이라면
openclaw pairing approve telegram 123456

페어링이 완료되면 “Pairing approved!” 같은 성공 메시지가 나타나고, 이제 텔레그램에서 AI 비서와 자유롭게 대화할 수 있어요! 🎉

페어링이 안 될 때 대안: allowFrom 설정

만약 페어링 코드가 정상적으로 동작하지 않을 경우, 텔레그램 봇과 소통할 사용자(본인)의 유저명이나 유저ID를 직접 입력하는 방법도 있습니다. 본인의 유저명이나 유저ID를 모르시면, @userinfobot이나 @Get my ID Bot을 검색해서 /start를 보내면 나의 텔레그램 ID(숫자)를 알려줍니다.

👥 그룹 채팅에서 사용하기

개인 채팅뿐만 아니라 그룹 채팅에서도 AI 비서를 사용할 수 있어요! 가족 그룹이나 팀 채팅에서 함께 AI 비서를 활용하면 정말 편리합니다. 다만 기본적으로 텔레그램 봇은 그룹에서 @멘션이 있는 메시지만 받아요. 모든 메시지를 받으려면 추가 설정이 필요합니다.

방법 1: Privacy Mode 비활성화

BotFather에서 봇의 Privacy Mode를 비활성화하면 그룹의 모든 메시지를 받을 수 있어요:

  1. BotFather와의 채팅에서 /setprivacy 명령어 입력
  2. 봇 목록에서 내 봇 선택
  3. “Disable” 버튼 클릭
  4. “Success! The new status is: DISABLED.” 메시지 확인

⚠️ 중요: Privacy Mode를 변경한 후에는 봇을 그룹에서 제거했다가 다시 추가해야 적용됩니다! 이미 그룹에 추가된 봇은 설정 변경이 즉시 반영되지 않아요.

방법 2: 봇을 그룹 관리자로 지정

Privacy Mode를 비활성화하지 않아도, 봇을 그룹 관리자로 지정하면 모든 메시지를 받을 수 있어요:

  1. 텔레그램 그룹 채팅방 열기
  2. 그룹 이름 클릭 → 그룹 정보 화면
  3. 멤버 목록에서 봇 찾기 → 봇 이름 클릭
  4. “Promote to Admin” (관리자로 승격) 선택

개인 봇이라면 방법 1이 편하고, 특정 그룹에서만 쓴다면 방법 2도 괜찮아요.

🎯 실전 활용 예시

연동이 완료되었다면 이제 진짜 재미있는 것들을 해볼 차례예요! 먼저 봇에게 개성있는 이름을 지어주면 애착이 생겨요:

💬 나: "너 이름이 뭐야?"
🤖 봇: "저는 아직 이름이 없어요. 지어주시겠어요?"
💬 나: "오늘부터 넌 '토비'야. 기억해"
🤖 봇: "알겠습니다! 저는 이제 토비예요. 기억할게요 😊"

OpenClaw는 대화 내용을 기억하므로, 다음에 “토비야”라고 부르면 알아듣는답니다!

일상적인 대화 예시

  • “오늘 서울 날씨 어때?” – 실시간 날씨 정보 확인 (웹 검색 스킬 필요)
  • “이 영어 문장 번역해줘: I’m excited to try this!” – 번역
  • “Python으로 피보나치 함수 짜줘” – 코드 생성
  • “내일 일정 알려줘” – 캘린더 연동 시 일정 확인

파일 및 이미지 처리

  • 사진을 보내고 “이 사진에 뭐가 있어?” – 이미지 분석
  • PDF 파일을 보내고 “이 문서 요약해줘” – 문서 요약
  • “어제 받은 파일 중 ‘보고서’ 들어간 거 찾아줘” – 파일 검색

업무 자동화

  • “어제 받은 파일 중 ‘보고서’ 들어간 거 PDF로 바꿔서 메일 보내줘”
  • “오늘 할 일 목록에 ‘블로그 쓰기’ 추가해”
  • “GitHub에서 내 리포지토리 목록 보여줘”
  • “애플 주가 얼마야?”
  • “지금 내 컴퓨터에서 실행 중인 앱 뭐야?”

스킬이 설치되어 있으면 더 다양한 기능을 사용할 수 있어요. ClawHub(clawhub.com)에서 다양한 스킬을 찾아볼 수 있습니다!

🔧 문제 해결 (트러블슈팅)

연동 과정에서 문제가 생길 수 있어요. 자주 발생하는 문제와 해결 방법을 정리했습니다:

1. 봇이 메시지에 응답하지 않을 때

  • 게이트웨이가 실행 중인지 확인: openclaw status
  • 게이트웨이 재시작: openclaw gateway restart
  • 로그 확인: openclaw logs

2. 페어링 코드가 작동하지 않을 때

allowFrom 설정에 본인의 텔레그램 사용자명이나 ID를 직접 입력해 보세요. 본인의 ID를 모른다면 @userinfobot이나 @Get my ID Bot에게 /start를 보내면 확인할 수 있어요.

3. 연동이 계속 안 될 때

기존에 텔레그램을 연동했던 이력이 있으면 충돌이 발생할 수 있어요. 이럴 때는 OpenClaw를 완전히 삭제하고 재설치해 보세요:

# OpenClaw 삭제
npm uninstall -g openclaw

# 설정 파일 삭제
rm -rf ~/.openclaw

# 재설치
npm install -g openclaw@latest

# 다시 설정
openclaw onboard

4. 토큰이 노출되었을 때

실수로 토큰을 공개했다면 즉시 BotFather에서 /revoke 명령어로 토큰을 재발급받으세요! 그리고 OpenClaw 설정에서 새 토큰으로 업데이트하세요.

🔐 보안 주의사항

OpenClaw는 내 컴퓨터의 파일 관리와 터미널 권한을 직접 가집니다. 영화 속 자비스처럼 편리하지만, 그만큼 보안에도 신경 써야 해요:

  • 개인 PC나 신뢰할 수 있는 서버에서만 실행하세요. 공용 컴퓨터에서는 사용하지 마세요.
  • 봇 토큰은 절대 공개하지 마세요. GitHub에 올리거나 블로그에 공유하면 안 됩니다.
  • allowFrom 설정으로 허용된 사용자만 접근하도록 제한하세요. 모르는 사람이 봇에 접근하면 위험할 수 있어요.
  • 정기적으로 토큰을 갱신하는 것이 좋아요. BotFather의 /revoke 명령으로 언제든 새 토큰을 발급받을 수 있습니다.
  • 민감한 정보는 봇을 통해 처리하지 않는 것이 좋아요. 비밀번호나 금융 정보 등은 직접 처리하세요.

✨ 마무리

오늘은 OpenClaw를 텔레그램과 연동하는 방법을 알아봤어요. 처음에는 복잡해 보일 수 있지만, 한 번 설정해 두면 정말 편리하게 AI 비서를 활용할 수 있답니다!

출퇴근길에, 회의 중에, 심지어 침대에서도 스마트폰 하나로 AI에게 명령을 내릴 수 있다니, 정말 영화 속 자비스가 현실이 된 것 같지 않나요? 🎬 “AI 비서가 CLI에서만 동작한다면, 그건 비서가 아니라 그냥 도구다”라는 말처럼, 메신저 연동이야말로 OpenClaw의 진정한 가치를 느낄 수 있는 방법입니다.

텔레그램 연동에 성공했다면, 다음 단계로 디스코드나 슬랙 연동에도 도전해 보세요. OpenClaw는 여러 채널을 동시에 지원하니까 상황에 맞는 채널을 선택해서 사용할 수 있어요! 업무는 슬랙으로, 개인은 텔레그램으로, 가족은 왓츠앱으로 – 이렇게 분리해서 사용하면 더욱 효율적입니다.

궁금한 점이 있으시면 댓글로 남겨주세요. 공식 문서(docs.openclaw.ai)와 디스코드 커뮤니티도 많은 도움이 될 거예요. 즐거운 AI 비서 생활 되세요! 🚀