OpenClaw로 텔레그램 AI 비서 만드는 방법 (실제 설정 가이드)

OpenClaw를 텔레그램 봇과 연결하면, 텔레그램에서 메시지를 보내는 것만으로 AI 에이전트를 사용할 수 있다. 이 글에서는 실제 설정 과정을 순서대로 정리한다.

공식 문서: https://docs.openclaw.ai/channels/telegram

사전 준비

Node.js 22 이상
Anthropic API 키 (또는 다른 모델 프로바이더 키)
텔레그램 계정

1단계: OpenClaw 설치

npm install -g openclaw
openclaw setup

openclaw setup 과정에서 API 키를 입력하게 된다. Anthropic API 키를 사용하면 Claude 모델을 바로 쓸 수 있다.

2단계: 텔레그램 봇 생성

텔레그램에서 @BotFather에게 DM을 보낸다:

/newbot 명령어 입력
봇 이름 입력 (예: "My AI Assistant")
봇 유저네임 입력 (예: my_ai_assistant_bot -- _bot으로 끝나야 함)
BotFather가 봇 토큰을 발급해줌 (예: 7123456789:AAH...)

이 토큰을 복사해둔다.

추가 설정 (선택):
- /setdescription -- 봇 설명 설정
- /setuserpic -- 봇 프로필 사진 설정
- /setcommands -- 커스텀 명령어 메뉴 설정

3단계: OpenClaw에 텔레그램 채널 설정

~/.openclaw/openclaw.json 파일을 편집한다:

{
  "channels": {
    "telegram": {
      "enabled": true,
      "botToken": "7123456789:AAH..."
    }
  }
}

이것만으로 기본 동작은 한다. 게이트웨이를 시작하면 텔레그램 봇이 long polling 모드로 메시지를 받기 시작한다.

4단계: 게이트웨이 시작

openclaw gateway start

이제 텔레그램에서 봇에게 DM을 보내면 AI가 응답한다.

5단계: 접근 제어 설정

기본 DM 정책은 pairing이다. 처음 메시지를 보내면 페어링 승인이 필요하다. 특정 사용자만 허용하려면 allowlist를 설정한다.

텔레그램 유저 ID 확인 방법

봇에게 DM을 보낸다
openclaw logs --follow 명령어로 로그를 확인한다
from.id 필드에서 숫자 ID를 확인한다

또는 텔레그램에서 @userinfobot에게 메시지를 보내면 자신의 ID를 알려준다.

allowlist 설정 예시

{
  "channels": {
    "telegram": {
      "enabled": true,
      "botToken": "7123456789:AAH...",
      "dmPolicy": "allowlist",
      "allowFrom": ["123456789", "987654321"]
    }
  }
}

그룹 설정

텔레그램 그룹에서 봇을 사용하려면 추가 설정이 필요하다.

{
  "channels": {
    "telegram": {
      "enabled": true,
      "botToken": "7123456789:AAH...",
      "groups": {
        "-1001234567890": {
          "groupPolicy": "open",
          "requireMention": true
        }
      }
    }
  }
}

groupPolicy: "open" -- 그룹 내 모든 멤버가 사용 가능
requireMention: true -- @봇유저네임으로 멘션해야 응답 (기본값)

그룹 채팅 ID 확인: 그룹 메시지를 @userinfobot에게 포워드하거나, openclaw logs --follow에서 chat.id를 확인한다.

모든 그룹에서 멘션 없이 응답하게 하려면:

{
  "channels": {
    "telegram": {
      "groups": {
        "*": { "requireMention": false }
      }
    }
  }
}

추가 설정 옵션

스트리밍 모드

텔레그램에서는 메시지 편집 방식으로 스트리밍을 구현한다. streamMode 설정으로 제어 가능하다.

웹훅 모드

기본은 long polling이지만, 서버 환경에서는 웹훅이 더 효율적일 수 있다:

{
  "channels": {
    "telegram": {
      "webhookUrl": "https://your-domain.com/telegram/webhook",
      "webhookSecret": "your-secret"
    }
  }
}

미디어 제한

mediaMaxMb 설정으로 처리할 미디어 파일 크기 제한을 설정할 수 있다.

유용한 명령어

게이트웨이 실행 중 사용할 수 있는 슬래시 명령어:
- /activation always -- 그룹에서 멘션 없이 항상 응답
- /activation mention -- 멘션 시에만 응답

정리

텔레그램은 OpenClaw에서 가장 설정이 간단한 채널이다. BotFather에서 토큰 발급, 설정 파일에 토큰 입력, 게이트웨이 시작 -- 이 세 단계면 기본 동작한다. 접근 제어와 그룹 설정은 필요에 따라 추가하면 된다.

전체 설정 레퍼런스: https://docs.openclaw.ai/gateway/configuration-reference#telegram