OpenClaw 설치부터 텔레그램 연동까지: 나만의 AI 에이전트 만들기

OpenClaw란?

OpenClaw는 오픈소스 AI 에이전트 게이트웨이입니다. 쉽게 말하면, 내가 쓰는 메신저(텔레그램, 디스코드, 슬랙 등)에 GPT나 Claude 같은 AI 모델을 연결해주는 도구입니다.

GitHub 스타 325,000개 이상, MIT 라이선스, TypeScript 기반이고 셀프 호스팅이 가능합니다. 설치하면 내 컴퓨터에서 AI 에이전트가 돌아가고, 메신저로 바로 대화할 수 있습니다.

이번 글에서는 OpenClaw를 설치하고, 텔레그램 봇을 연결해서 첫 AI 답변을 받기까지 한 번에 따라가 봅니다.

바로 시작해보기

설치는 한 줄이면 됩니다. 자신의 OS에 맞는 명령어를 실행하세요.

macOS / Linux — 터미널에서 실행:

curl -fsSL https://openclaw.ai/install.sh | bash

Windows — PowerShell에서 실행:

powershell -c "irm https://openclaw.ai/install.ps1 | iex"

설치 명령어만 다르고, 이후 설정 과정은 동일합니다. 자세한 설치 옵션은 OpenClaw 공식 사이트에서도 확인할 수 있습니다.

명령어를 실행하면 설치 스크립트가 알아서 환경을 감지하고, 필요한 의존성까지 자동으로 설치해줍니다.

💡install.sh가 하는 일

스크립트는 3단계로 동작합니다.

환경 감지 — OS 확인, 기존 설치 여부 체크
Node.js 설치 — Node.js가 없거나 v22 미만이면 자동 설치 (macOS는 Homebrew, Linux는 apt/dnf, Windows는 winget 사용)
OpenClaw 설치 — npm install -g openclaw으로 글로벌 설치

| 항목 | 자동 설치 여부 | |------|-------------| | Node.js (v22) | ✅ 자동 | | npm | ✅ Node.js에 포함 | | Homebrew (macOS) | ✅ 없으면 자동 | | 빌드 도구 (Linux) | ✅ 자동 | | Git | ❌ 직접 설치 안 함 (간접적으로 딸려올 수 있음) | | OpenClaw | ✅ npm -g로 설치 |

설치 후 초기 설정

설치 명령어를 실행하면 바로 초기 설정이 시작됩니다.

설치 시작 확인

설치를 시작할지 묻는 화면. Yes를 선택합니다.

AI 모델 선택과 인증

다음으로 어떤 AI 모델을 쓸지 고르는 단계입니다. OpenClaw는 OpenAI, Claude, Gemini 등 20개 이상의 프로바이더를 지원합니다.

AI 프로바이더 선택

다양한 프로바이더 중에서 가장 익숙한 OpenAI(GPT)를 선택했습니다.

인증 방식 선택

구독 플랜의 OAuth를 사용하기 위해 OpenAI Codex를 선택합니다.

OAuth 브라우저 인증

선택하면 브라우저가 열립니다. 계속 버튼을 클릭하면 인증이 진행됩니다.

모델 선택

OAuth 인증이 완료되면 사용할 모델을 선택하는 화면이 나옵니다. 원하는 모델을 고르면 됩니다.

텔레그램 봇 만들기

모델 설정이 끝나면 채널 선택 화면이 나옵니다. 텔레그램을 연결하려면 먼저 봇을 만들어야 합니다.

채널 선택 대기

터미널은 이 상태에서 잠시 대기하고, 텔레그램으로 이동합니다.

텔레그램 앱을 열고 BotFather를 통해 봇을 생성합니다. BotFather는 텔레그램의 공식 봇 관리 도구입니다.

BotFather 검색

텔레그램에서 "BotFather"를 검색합니다.

BotFather 시작

BotFather를 선택하고 Start를 누릅니다.

newbot 명령어

/newbot을 입력해서 새 봇 생성을 시작합니다.

봇 이름과 토큰 발급

봇 이름과 username을 입력합니다. username은 반드시 "bot"으로 끝나야 합니다. 이미 존재하는 username은 사용할 수 없으니 적절히 정해주세요. 생성이 완료되면 API 토큰이 발급됩니다.

OpenClaw에 텔레그램 연결

봇 토큰을 받았으면 다시 터미널로 돌아갑니다.

텔레그램 채널 선택

채널 목록에서 Telegram을 선택하고, "Enter Telegram bot token"을 선택합니다.

토큰 붙여넣기

텔레그램 채팅방에서 복사한 봇 토큰을 붙여넣습니다.

이후 몇 가지 추가 옵션을 물어보는데, 전부 나중에 추가할 수 있으니 지금은 넘어가도 됩니다.

Search provider 건너뛰기

Search provider는 Skip을 선택합니다.

Skills 건너뛰기

Skills도 No를 선택하고 넘어갑니다.

Hooks 건너뛰기

Hooks도 Skip하고 다음으로 진행합니다.

Web UI에서 동작 확인

설정이 끝나면 Web UI를 열어서 봇이 제대로 동작하는지 먼저 확인합니다.

Web UI 열기

"Open the Web UI"를 선택합니다. 텔레그램에서 바로 대화하려면 먼저 페어링이 필요하기 때문에, Web UI에서 테스트하는 게 순서입니다.

Web UI 화면

이런 웹 채팅 화면이 열립니다.

Web UI에서 테스트

간단한 메시지를 보내서 봇이 응답하는지 확인합니다. 여기서 답변이 오면 모델 연결은 성공입니다.

텔레그램 페어링

Web UI에서 동작을 확인했으면, 이제 텔레그램과 페어링할 차례입니다.

봇 검색

텔레그램에서 아까 만든 봇을 검색합니다.

페어링 코드 수신

봇을 찾아서 Start를 누르면 페어링 코드가 포함된 메시지를 보내줍니다.

Web UI에서 페어링 승인

그 메시지를 그대로 복사해서 Web UI 채팅창에 붙여넣습니다. 텔레그램 승인이 되었다는 메시지가 나오면 성공입니다.

텔레그램에서 첫 답변 받기

페어링이 끝나면 텔레그램에서 바로 AI와 대화할 수 있습니다.

텔레그램 첫 답변

텔레그램에서 메시지를 보내면 AI가 답변합니다. 여기까지 오면 설치와 연동이 모두 완료된 상태입니다.

중간에 막힐 수 있는 포인트

직접 해보면서 몇 가지 헷갈릴 수 있는 부분이 있었습니다.

텔레그램 봇 username — "bot"으로 끝나야 하고, 이미 다른 사람이 쓰고 있는 이름은 안 됩니다. 몇 번 시도해야 할 수도 있습니다.
토큰 복사 — BotFather가 보내주는 메시지에서 토큰 부분만 정확히 복사해야 합니다. 앞뒤 공백이 들어가면 인증이 실패합니다.
페어링 순서 — 텔레그램에서 바로 대화하면 응답이 안 옵니다. Web UI에서 먼저 페어링 코드를 입력해야 텔레그램이 연결됩니다.
Search/Skills/Hooks — 처음 설치할 때는 전부 건너뛰어도 됩니다. 나중에 설정 파일에서 언제든 추가할 수 있습니다.

이번 글 정리

이번 글에서 한 것을 정리하면 이렇습니다.

OpenClaw 설치 (터미널/PowerShell 한 줄)
OpenAI 모델 연결 (OAuth 인증)
텔레그램 봇 생성 (BotFather)
OpenClaw에 텔레그램 봇 토큰 등록
Web UI에서 동작 확인
텔레그램 페어링 완료
텔레그램에서 AI 첫 답변 수신

설치부터 첫 답변까지 실제로 걸린 시간은 약 15분 정도였습니다. 설치 스크립트가 대부분의 환경 세팅을 자동으로 해주기 때문에, 생각보다 빠르게 끝납니다.

다음 글 예고

다음 글에서는 OpenClaw의 모델 폴백(Fallback) 설정을 다룰 예정입니다. API 한도가 초과되거나 특정 모델이 응답하지 않을 때, 자동으로 다른 모델로 전환되도록 설정하는 방법입니다. 24시간 무중단 AI 에이전트를 운영하려면 꼭 필요한 설정입니다.

OpenClaw 완전 정복 시리즈(1편 중 1편)