OpenClaw Telegram 봇 연결 가이드

Telegram은 전 세계적으로 가장 널리 사용되는 메신저 중 하나이며, 강력한 Bot API 생태계를 보유하고 있습니다. OpenClaw이 제공하는 오픈소스 셀프 호스팅 AI 어시스턴트를 활용하면, 나만의 Telegram AI 봇을 손쉽게 만들어 언제 어디서든 Claude, GPT 등 대규모 언어 모델과 대화할 수 있습니다. 이 가이드에서는 OpenClaw과 Telegram을 연결하는 전체 과정을 자세히 설명합니다.

사전 요구사항

시작하기 전에 다음 준비가 완료되어 있는지 확인하세요:

Node.js 22 이상 설치 완료
OpenClaw 설치 및 초기화 완료 (openclaw onboard)
Telegram 계정 보유
OpenClaw 게이트웨이가 정상 실행 중 (기본 포트 18789)

아직 OpenClaw을 설치하지 않았다면, 다음 명령어로 빠르게 설치할 수 있습니다:

npm install -g openclaw@latest
openclaw onboard

설치 과정에서 AI 모델 공급자 선택과 API 키 설정을 포함한 기본 설정을 안내합니다.

1단계: BotFather로 Telegram 봇 생성

모든 Telegram 봇은 공식 @BotFather를 통해 생성하고 관리합니다. Telegram을 열고 @BotFather를 검색하여 대화를 시작한 다음, 아래 단계를 따릅니다:

/newbot 명령어를 보냅니다
BotFather가 봇의 표시 이름을 요청합니다. 예: My AI Assistant
이어서 사용자 이름을 설정해야 합니다. 반드시 bot으로 끝나야 합니다. 예: my_ai_assistant_bot
생성이 완료되면 BotFather가 Bot Token을 반환합니다. 7123456789:AAHxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx 형식입니다

중요: 이 토큰을 안전하게 보관하고 절대 타인에게 노출하지 마세요. 토큰이 있으면 봇을 완전히 제어할 수 있습니다.

BotFather를 통해 봇을 추가로 커스터마이징할 수도 있습니다:

/setdescription - 봇 설명 설정
/setabouttext - "소개" 정보 설정
/setuserpic - 프로필 사진 설정

2단계: OpenClaw에서 Telegram 채널 설정

Bot Token을 받았으면, OpenClaw 설정 파일에 추가해야 합니다. 설정 파일을 엽니다:

nano ~/.config/openclaw/openclaw.json5

설정 파일의 channels 섹션에 Telegram 채널 설정을 추가합니다:

{
  channels: {
    telegram: {
      enabled: true,
      botToken: "7123456789:AAHxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
      // 선택사항: 봇 사용을 허용할 사용자 ID 목록
      allowedUsers: [],
      // 선택사항: 그룹에서의 봇 트리거 방식
      groupBehavior: "mention", // "mention" @멘션 필요, "always" 항상 응답
    }
  }
}

파일을 저장한 후, OpenClaw 게이트웨이를 재시작하여 설정을 적용합니다:

openclaw gateway restart

3단계: 연결 상태 확인

설정이 완료되면, 내장 진단 도구로 연결이 정상인지 확인합니다:

openclaw doctor

이 명령은 모든 설정된 채널의 연결 상태를 검사합니다. Telegram 채널이 녹색 또는 "connected"로 표시되면 설정이 성공한 것입니다. Dashboard에서 더 자세한 상태 정보를 확인할 수도 있습니다:

openclaw dashboard

이제 Telegram을 열고 방금 만든 봇을 찾아서 메시지를 보내 테스트해 보세요. 정상적으로 설정되었다면 봇이 답변을 보내줄 것입니다.

4단계: 그룹에 봇 추가

OpenClaw의 Telegram 봇은 개인 채팅뿐만 아니라 그룹에 추가하여 여러 사람에게 서비스할 수도 있습니다. 다음과 같이 진행합니다:

대상 Telegram 그룹의 설정을 엽니다
"멤버 추가"를 클릭하고 봇의 사용자 이름을 검색합니다
봇을 그룹에 추가합니다

기본적으로 봇은 그룹에서 mention 모드로 작동합니다. 즉, 메시지에서 봇을 @멘션했을 때만 응답합니다. 이렇게 하면 봇이 모든 메시지에 답변하여 일반 채팅을 방해하는 것을 방지할 수 있습니다.

봇이 그룹의 모든 메시지에 응답하도록 하려면 groupBehavior를 "always"로 변경할 수 있지만, 이 설정은 AI 전용 토론 그룹에서만 사용하는 것이 좋습니다.

5단계: 개인정보 보호 모드 설정

Telegram 봇은 기본적으로 개인정보 보호 모드(Privacy Mode)가 활성화되어 있어, 그룹에서 봇이 볼 수 있는 메시지가 제한됩니다:

/로 시작하는 명령어
봇을 직접 @멘션한 메시지
봇의 메시지에 대한 답장

봇이 그룹의 모든 메시지를 볼 수 있어야 하는 경우 (예: 문맥 이해를 위해), BotFather에서 개인정보 보호 모드를 비활성화해야 합니다:

@BotFather에게 /mybots를 보냅니다
해당 봇을 선택합니다
Bot Settings → Group Privacy로 이동합니다
Turn off를 선택합니다

참고: 개인정보 보호 모드를 비활성화한 후에는, 봇을 그룹에서 제거하고 다시 추가해야 적용됩니다.

보안 권장사항

Telegram 봇을 운영할 때 보안은 매우 중요합니다:

사용자 접근 제한: allowedUsers에 봇 사용을 허용할 Telegram 사용자 ID를 입력하여, 낯선 사람이 AI 사용량을 남용하는 것을 방지하세요
게이트웨이 포트 보호: 18789 포트를 절대 외부에 직접 노출하지 말고, 반드시 Nginx 등의 리버스 프록시를 사용하세요
정기적인 토큰 교체: 토큰이 유출된 것으로 의심되면, 즉시 BotFather의 /revoke 명령으로 토큰을 재발급하세요

자신의 Telegram 사용자 ID는 @userinfobot에게 아무 메시지나 보내면 확인할 수 있습니다.

마무리

이 가이드를 통해 OpenClaw과 Telegram 연결이 완료되었으며, 개인 AI 챗봇을 갖게 되었습니다. 개인 채팅으로 빠르게 질문하거나, 업무 그룹에 추가하여 팀 협업을 돕는 데 활용할 수 있습니다. 더 많은 고급 설정과 활용 팁은 OpenClaw 공식 문서를 참고하세요. 설정 과정에서 문제가 발생하면 OpenClaw GitHub 저장소에서 이슈를 확인하거나 피드백을 남겨주세요.