이 포스팅은 쿠팡 파트너스 활동의 일환으로, 이에 따른 일정액의 수수료를 제공받습니다.
오픈클로 텔레그램 봇 만들기, 봇파더 토큰과 제미나이 API 연결법
오픈클로 텔레그램 봇 만들기를 Mac mini 기준으로 30단계에 정리했습니다. BotFather에서 봇 토큰을 받아 OpenClaw에 붙이고, 모델은 Google Gemini API 키로 연결하는 흐름입니다. Homebrew·

오픈클로 텔레그램 봇으로 할 수 있는 일
이런 장면을 떠올리면 쉽습니다. 밖에서 커피를 마시는데 동료가 지난주 작업한 제안서를 보내 달라고 합니다. 컴퓨터에는 손이 닿지 않습니다. 휴대폰으로 AI 비서에게 "그 제안서를 찾아서 이 메일로 보내"라고 시키면 끝입니다.
그 비서 역할을 하는 프로그램이 OpenClaw입니다. ClawdBot, Moltbot이라는 이름으로 알려졌던 프로그램과 같은 것이고, 이름이 바뀌어 왔을 뿐입니다. 옛 이름으로 검색해 들어왔다면 지금은 OpenClaw로 찾으면 됩니다.
OpenClaw와 대화하는 창구로는 지금으로서는 Telegram이 가장 무난합니다. 앞으로는 바뀔 수도 있습니다. Telegram은 봇을 누구나 무료로 만들 수 있고, 토큰 하나만 있으면 외부 프로그램과 연결되기 때문에 개인 에이전트용 채널로 가장 흔히 쓰입니다.
설치 전에 알아 둘 두 가지
설치에는 Homebrew, Node.js, PNPM, OpenClaw 네 가지 명령이 필요합니다. 1~7단계에 각 도구의 공식 설치 명령을 적었습니다.
테스트 직전에는 봇의 actions를 켜고 enable로 바꾸는 설정이 있습니다. 이 부분과, 봇이 답하지 않을 때 확인할 것들은 6장에 정리했습니다.
보안: 컴퓨터 전체 접근 권한의 위험
OpenClaw는 무료, 오픈소스이고 내 기기에서 돌아갑니다. 컴퓨터 전체에 접근할 수 있어 삶을 편하게 해 준다는 점이 장점으로 꼽힙니다. 하지만 같은 이유로 위험도 큽니다.
휴대폰 메시지로 내 컴퓨터 전체를 움직이는 구조라서, Telegram 봇 토큰이 새면 다른 사람이 같은 권한을 쓸 수 있습니다. 토큰과 API 키는 공개하지 말고, 스킬로 연결하는 앱(Apple Notes, GitHub 등)과 접근 범위는 필요한 만큼만 두는 편이 안전합니다. 가능하면 개인 파일과 계정이 없는 전용 Mac mini나 전용 사용자 계정에 설치합니다.
준비물: 맥미니, 제미나이 API 키, 텔레그램
- Mac mini: 초기 설정(언어, Apple ID, 사용자 계정)이 끝난 상태.
- 터미널: Cmd+Space로 Spotlight를 열고 "terminal"을 입력하면 열립니다.
- 모델 API 키: 이 글은 Google Gemini API 키를 씁니다. 발급 방법은 바로 아래에 정리했습니다.
- Telegram 앱(휴대폰 또는 컴퓨터)
- (스킬을 쓰려면) Apple Notes, GitHub 계정
- 비용: OpenClaw 자체는 "무료, 오픈소스"입니다. 모델 API 사용료는 따로입니다. Gemini API는 무료 사용 구간이 있지만 한도와 요금은 자주 바뀌니 Google 공식 안내를 확인해야 합니다.
Gemini API 키(내 Google 계정으로 Gemini 모델을 부를 수 있게 해 주는 비밀 문자열)는 Google AI Studio에서 만듭니다.
- 브라우저에서 aistudio.google.com에 들어가 Google 계정으로 로그인합니다.
- 왼쪽 메뉴나 오른쪽 위의 "Get API key"를 누릅니다.
- "Create API key"를 누르고, 나온 키를 복사해 메모장에 잠시 붙여 둡니다.
- 키는 비밀번호처럼 다룹니다. 화면 캡처나 채팅에 올리지 않습니다.
1. 사전 설치: Homebrew, Node.js, PNPM
순서 고정입니다. Homebrew를 마친 뒤 Node.js를 설치하고, Node.js가 있어야 PNPM을 설치합니다.
- Homebrew: 맥용 프로그램 설치 관리자
- Node.js: OpenClaw가 돌아가는 실행 환경
- PNPM: Node.js 프로그램 설치 도구의 하나. npm보다 빠르고 용량을 덜 쓰는 대안입니다.
- 터미널에서 Homebrew를 설치한다.
- 위치: 터미널. brew.sh 첫 화면에 있는 공식 명령은 아래와 같습니다.
- 확인: Homebrew 설치가 끝난다. Mac 비밀번호를 한 번 묻고, 끝나면 안내 문구가 나온다.
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
- 주의: 설치가 끝날 때 "Next steps"로 PATH 설정 명령 두 줄을 보여 주는 경우가 있습니다. 그 두 줄을 그대로 복사해 실행해야
brew명령이 먹습니다. 2. Homebrew로 Node.js를 설치한다.- 위치: 터미널. 명령은 아래와 같습니다.
- 확인: Node.js 설치가 끝난다.
node -v를 입력하면 버전 번호가 나온다.
brew install node
- PNPM을 설치한다.
- 위치: 터미널. Node.js에 딸려 오는 npm으로 설치합니다.
brew install pnpm으로 해도 됩니다. - 확인: PNPM 설치가 끝나고 필요한 도구가 다 갖춰진 상태가 된다.
pnpm -v로 확인할 수 있다.
- 위치: 터미널. Node.js에 딸려 오는 npm으로 설치합니다.
npm install -g pnpm
2. OpenClaw 설치 시작
- 브라우저에서 OpenClaw 웹사이트에 들어간다.
- 위치: 공식 주소는 openclaw.ai입니다. 이름이 여러 번 바뀌면서 비슷한 가짜 사이트가 생겼으니 주소를 꼭 확인합니다.
- 확인: 설치 명령이 보이는 페이지가 뜬다.
- 페이지의 설치 명령을 복사한다.
- 위치: Quick Start 항목의 one-liner(한 줄 설치 명령). 공식 명령은 아래 형태이고, 사이트와 다르면 사이트를 따릅니다.
- 확인: 클립보드에 명령이 들어 있다.
curl -fsSL https://openclaw.ai/install.sh | bash
- 터미널로 돌아간다.
- 확인: 터미널 창이 앞에 있다.
- 복사한 명령을 붙여 넣어 실행한다.
- 확인: 설정이 시작되고 몇 가지 질문과 권한 요청이 나온다. 첫 질문은 보통 "위험을 이해했느냐"는 동의이고, 이어서 QuickStart 같은 설정 방식을 고릅니다.
설정 화면이 자동으로 뜨지 않으면 openclaw onboard
3. 제미나이 API로 모델 제공자 선택
- 제공자(provider) 목록에서 Google Gemini를 고른다.
- 대안: 제공자는 각자 고르면 됩니다. 어떤 건 API 키만 있으면 되고, 추론(reasoning, 답하기 전에 단계를 밟아 생각하는 방식) 모델을 쓰는 건 인증(authentication)도 필요합니다.
- 확인: API 키 입력 칸이 뜬다.
- Gemini API 키를 입력한다.
- 주의: 키 값은 공개하지 않습니다. 앞의 준비물에서 AI Studio로 만든 키를 붙여 넣습니다.
- 확인: 모델 선택 화면이 뜬다.
- 사용할 모델을 고른다.
- 확인: 채널 선택 화면이 뜬다. 처음에는 목록의 기본값을 두고, 나중에
openclaw configure로 바꿔도 됩니다.
- 확인: 채널 선택 화면이 뜬다. 처음에는 목록의 기본값을 두고, 나중에
4. 텔레그램 봇 만들기와 오픈클로 연결
- 채널 목록에서 Telegram을 고른다.
- 대안: 다른 채널도 있지만 Telegram이 가장 간단하고 직관적입니다.
- 확인: "Telegram 봇 토큰을 입력하라"는 단계가 뜬다.
- Telegram 앱을 연다.
- 확인: Telegram이 열린다. 터미널 화면은 그대로 둡니다.
- 검색창에서 BotFather의 사용자명을 검색한다.
- 위치: 검색창에
@BotFather를 입력합니다. 이름 옆에 파란 인증 표시가 있는 계정이 진짜입니다. - 확인: 검색 결과에 BotFather가 뜬다.
- 위치: 검색창에
- BotFather를 연다.
- 확인: BotFather 대화창이 열린다.
- BotFather의 앱(Open)을 연다.
- 확인: 봇 관리 화면이 뜬다. 보통 대화창 아래쪽의 Open 버튼입니다. 버튼이 없으면 대화창에
/newbot을 보내도 같은 과정이 시작됩니다.
- 확인: 봇 관리 화면이 뜬다. 보통 대화창 아래쪽의 Open 버튼입니다. 버튼이 없으면 대화창에
- "create a new bot"을 누른다.
- 확인: 봇 이름 입력 칸이 뜬다.
- 봇 이름을 입력한다.
- 확인: 이름 칸이 채워진다. 화면에 보이는 이름이라 한글도 됩니다.
- 봇 사용자명(username)을 입력한다.
- 확인: 사용자명 칸이 채워진다. Telegram 규칙상 영문·숫자·밑줄만 쓸 수 있고 끝이
bot으로 끝나야 합니다(예: my_home_helper_bot). 이미 쓰는 이름이면 다른 이름을 요구합니다.
- 확인: 사용자명 칸이 채워진다. Telegram 규칙상 영문·숫자·밑줄만 쓸 수 있고 끝이
- 봇을 생성한다.
- 확인: 토큰이 표시된다. 숫자, 쌍점(:), 영문이 섞인 긴 문자열입니다.
- 토큰을 복사한다.
- 주의: 토큰 값은 공개하지 않습니다. 새었다면 BotFather에서 토큰을 새로 발급(revoke)받아 교체합니다.
- 확인: 클립보드에 토큰이 있다.
- 터미널의 설정 화면으로 돌아간다.
- 확인: 토큰 입력 칸이 보인다.
- 토큰을 붙여 넣는다.
- 확인: "스킬이나 다른 소스·앱 연결을 설정할까요?" 질문이 뜬다.
5. 스킬과 게이트웨이 설정
스킬은 에이전트에 붙이는 추가 기능(메모 앱, 코드 저장소 연결 등)이고, 게이트웨이는 OpenClaw가 뒤에서 계속 켜 두는 중계 프로그램입니다. Telegram에서 온 메시지를 받아 모델에 넘기는 일을 게이트웨이가 합니다.
- 스킬 설정 질문에 "Yes"로 답한다.
- 확인: 노드 매니저 선택이 뜬다.
- 노드 매니저로 npm을 고른다.
- 위치: 1장에서 PNPM을 설치했으니 pnpm을 골라도 됩니다.
- 확인: 설치할 앱(스킬) 목록이 뜬다.
- 목록에서 원하는 앱을 고른다.
- 대안: 예를 들어 Apple Notes와 GitHub를 고를 수 있습니다. 지금 고르지 않고 나중에 설치해도 됩니다. 목록 화면은 보통 스페이스로 고르고 Enter로 넘어갑니다.
- 확인: 선택이 끝나고 다음 질문이 뜬다.
- 이어서 묻는 API 키 설정에 "No"를 고른다.
- 대안: 나중에 설정할 수 있으니 지금은 No로 넘어가도 됩니다. 이미지 생성, 음성 인식 같은 부가 기능용 키가 차례로 나오는 경우가 많습니다.
- 확인: 게이트웨이 서비스 질문이 뜬다.
- 게이트웨이 서비스 선택지에서 첫 번째를 고른다.
- 대안: 이미 컴퓨터에 게이트웨이 서비스가 있으면 건너뛰거나 재설치해도 됩니다. 처음 설치라면 서비스로 설치해 Mac이 켜질 때 자동으로 돌게 하는 쪽이 편합니다.
- 확인: 설정이 끝난다("That's it", "There you go").
6. 텔레그램에서 쓰기 위한 설정과 테스트
Telegram에서 봇을 쓰려면 마지막으로 몇 가지를 바꿔야 합니다. 설정 마법사를 다시 열어 Telegram 채널 항목을 손보는 단계입니다.
- 봇의 "actions"를 켠다.
- 위치: 터미널에서
openclaw configure를 실행하고 채널 설정에서 Telegram을 고릅니다. - 확인: actions가 켜져 있다.
- 위치: 터미널에서
- 해당 항목을 "enable"로 설정한다.
- 위치: 같은 Telegram 채널 설정 화면. 입력 칸이 나오면 안내 문구에 따라 값을 넣습니다.
- 확인: enable로 바뀌어 있다.
- 저장한다.
- 확인: Telegram에서 봇에게 말을 걸면 답한다("There you go").
메뉴 이름은 버전에 따라 다를 수 있습니다. 봇이 답하지 않을 때는 아래 순서로 확인합니다.
첫째, 페어링 승인입니다. OpenClaw는 기본적으로 모르는 사람의 메시지에 바로 답하지 않고, 처음 말을 건 사람에게 페어링 코드(이 사람과 대화해도 되는지 주인이 승인하는 번호)를 보냅니다. 봇이 코드를 보냈다면 Mac mini 터미널에서 승인합니다. 명령 형식은 버전에 따라 다를 수 있으니 openclaw pairing --help
openclaw pairing approve telegram 페어링코드
둘째, 게이트웨이가 돌고 있는지 봅니다. 설정을 바꾼 뒤에는 게이트웨이를 다시 시작해야 반영됩니다.
openclaw gateway restart
셋째, 토큰을 다시 넣어야 할 수도 있습니다. 토큰을 잘못 붙였거나 봇을 새로 만들었다면 openclaw channels add
첫 테스트 메시지는 결과를 바로 확인할 수 있는 가벼운 것으로 보냅니다.
안녕, 지금 연결된 모델 이름과 오늘 날짜를 알려 줘.
오픈클로 텔레그램 연결 체크리스트
- Homebrew, Node.js, PNPM이 설치돼 있다
- OpenClaw 설정 마법사를 끝까지 마쳤다
- Telegram 봇 토큰이 입력돼 있다
- Telegram에서 봇이 답한다
처음부터 다시 하고 싶다면 openclaw uninstall
오픈클로 텔레그램 설치 흐름 한 번에 보기
전체 흐름은 짧습니다. 사전 설치 3개, 설치 명령 복사, 마법사에서 Gemini와 Telegram 고르기, BotFather 토큰 붙여 넣기, 스킬 선택, 게이트웨이까지입니다.
막히는 곳은 대개 두 군데입니다. 설치 명령은 1~2장의 공식 명령을 그대로 쓰고, 테스트에서 봇이 조용하면 6장의 페어링 승인과 게이트웨이 재시작을 차례로 점검합니다. 컴퓨터 전체 접근을 주는 도구이니 토큰 관리와 전용 계정 설치는 처음부터 챙기는 게 좋습니다.
자주 묻는 질문
오픈클로 텔레그램 봇 토큰은 어디서 받나요?
Telegram의 BotFather에서 받습니다. @BotFather/newbot(또는 create a new bot)을 누른 뒤, 봇 이름과 bot
텔레그램 봇이 메시지에 답하지 않으면 어떻게 하나요?
먼저 봇이 페어링 코드를 보냈는지 봅니다. 보냈다면 Mac mini 터미널에서 openclaw pairing approve telegram 코드 형식으로 승인합니다. 그래도 조용하면 openclaw gateway restart
제미나이 API로 오픈클로를 쓰면 무료인가요?
OpenClaw 자체는 무료, 오픈소스이고 모델 API 사용료는 따로입니다. Gemini API에는 무료 사용 구간이 있지만 한도와 요금은 자주 바뀌니 Google 공식 안내를 확인해야 합니다.
클로드봇, 몰트봇, 오픈클로는 다른 프로그램인가요?
같은 프로그램의 옛 이름과 지금 이름입니다. 이름은 바뀌었지만 쓰는 법은 같습니다. 지금 설치하려면 OpenClaw 공식 주소인 openclaw.ai에서 받습니다.
이 글의 본문은 아래 원본 유튜브 영상의 내용을 바탕으로 쓸모연구소가 다시 정리해 쓴 것입니다. 세부 내용과 최신 정보는 원본 영상과 공식 안내에서 확인해 주세요.
원본 영상 보러가기 ↗