OpenClaw Telegram 연동 2단계: 봇 토큰 발급과 보관 방법

텔레그램 연동은 겉으로 보면 간단합니다. BotFather에서 봇을 만들고 토큰을 받아 OpenClaw에 넣으면 끝날 것 같지만, 실제로는 여기서 많이 헷갈립니다. 토큰을 어디에 넣는지, 설정 파일에 직접 적는지, 터미널에서 다시 등록하는지, 그리고 이 값을 어떻게 보관해야 하는지까지 한 번에 정리되지 않으면 중간에 멈추기 쉽습니다.

특히 OpenClaw는 메신저를 통해 AI 에이전트와 연결되는 구조라서, 텔레그램 봇 토큰이 사실상 연결 열쇠 역할을 합니다. 그래서 발급만 받는 것보다 더 중요한 건 “유출되지 않게 저장하는 방법”입니다. 이번 단계에서는 실제로 따라 할 수 있게 BotFather 명령어, OpenClaw에 입력하는 코드, 설정 파일 예시, 그리고 보관 팁까지 같이 정리해보겠습니다.

먼저 알아둘 점

텔레그램 봇 토큰은 보통 숫자:문자열 형태로 발급됩니다. 예를 들면 123456789:AA... 같은 형식입니다. 이 값은 OpenClaw가 텔레그램 Bot API에 접속할 때 쓰는 인증값이라서, 비밀번호처럼 다뤄야 합니다. 최근 가이드들에서도 텔레그램 연동 과정은 대부분 BotFather에서 토큰 생성 → OpenClaw에 토큰 등록 → 텔레그램에서 /start → 페어링 승인 순서로 설명됩니다.

중요한 점은 토큰만 있다고 바로 안전하게 끝나는 게 아니라는 점입니다. OpenClaw 쪽에서는 페어링 코드 승인 절차를 한 번 더 거치도록 안내하는 사례가 많고, 허용 사용자 ID를 제한하는 방식도 함께 사용됩니다. 이 단계가 있어야 다른 사람이 우연히 봇을 찾아 메시지를 보내는 상황을 줄일 수 있습니다.

1. BotFather에서 텔레그램 봇 토큰 발급하기

텔레그램에서 @BotFather를 검색한 뒤 대화를 시작합니다. 그다음 아래 순서대로 진행하면 됩니다.

/newbot

먼저 봇 이름을 입력합니다. 이 이름은 사용자에게 보여지는 이름이라 어느 정도 자유롭게 정해도 됩니다.

OpenClaw Helper

그다음 봇의 사용자명(username)을 입력합니다. 이 값은 고유해야 하고, 보통 끝에 bot이 들어가야 합니다.

openclaw_helper_bot

정상적으로 생성되면 BotFather가 아래와 비슷한 형태의 토큰을 보내줍니다.

123456789:AAEXAMPLE_TOKEN_REPLACE_THIS

이 토큰이 바로 OpenClaw에 넣을 값입니다. 화면에 보인다고 해서 그대로 채팅방에 오래 남겨두거나, 블로그 초안이나 메모 앱에 평문으로 여러 번 복붙해 두는 방식은 권장하기 어렵습니다. 실제 사용에서는 한 번만 복사해서 안전한 위치에 저장하고, 이후 설정이 끝나면 불필요한 중복 저장본은 정리하는 편이 낫습니다.

2. OpenClaw 온보딩에서 토큰 입력하기

최근 예시들을 보면 가장 많이 쓰이는 방법은 OpenClaw 온보딩을 다시 열어서 텔레그램 채널 값을 갱신하는 방식입니다. 이미 게이트웨이가 실행 중이라면 먼저 중지한 뒤 설정을 다시 진행합니다.

openclaw gateway stop
openclaw onboard

온보딩 중간에 채널 선택 화면이 나오면 Telegram (Bot API)를 선택하고, 방금 발급받은 토큰을 붙여 넣습니다.

Bot Token:
123456789:AAEXAMPLE_TOKEN_REPLACE_THIS

이 방식은 CLI 흐름이 비교적 단순해서 초보자가 따라가기 편한 편입니다. 실제로 최근 OpenClaw 사용자 가이드들에서도 게이트웨이를 멈춘 뒤 openclaw onboard를 실행하고, 설정 갱신 후 텔레그램 토큰을 입력하는 순서가 자주 소개됩니다.

3. 채널 추가 명령으로 등록하는 방식

환경에 따라 온보딩 전체를 다시 돌리기보다 채널만 추가하는 방식이 더 편할 때도 있습니다. 최근 예시 중에는 아래처럼 채널 추가 명령을 먼저 실행한 뒤 Telegram을 선택하는 흐름도 보입니다.

openclaw channels add

이후 프롬프트가 뜨면 Telegram을 선택하고 토큰을 넣습니다.

Select channel: Telegram (Bot API)
Enter bot token: 123456789:AAEXAMPLE_TOKEN_REPLACE_THIS

설치 초기에 전체 구성을 다시 확인하고 싶다면 온보딩 방식이 낫고, 이미 나머지 설정은 끝났는데 텔레그램만 추가하려는 경우에는 채널 추가 방식이 더 덜 번거로울 수 있습니다.

4. 설정 파일에 직접 넣는 예시

일부 환경에서는 설정 파일을 직접 관리하는 방식이 더 편할 수 있습니다. 공개된 예시 중에는 ~/.openclaw/openclaw.json 안에 텔레그램 플러그인 설정을 넣는 형태가 소개됩니다. 예시는 아래처럼 작성할 수 있습니다.

{
  "plugins": {
    "telegram": {
      "token": "123456789:AAEXAMPLE_TOKEN_REPLACE_THIS",
      "allowedUsers": [123456789]
    }
  }
}

여기서 token에는 BotFather에서 받은 토큰을 넣고, allowedUsers에는 봇 사용을 허용할 텔레그램 사용자 ID를 숫자로 넣습니다. 이 값은 사용자명(@아이디)이 아니라 숫자 ID 기준으로 다루는 예시가 많습니다. 그래서 초보자는 “내 텔레그램 아이디를 넣으면 되겠지”라고 생각하다가 여기서 한 번 막히는 경우가 있습니다.

5. 내 텔레그램 사용자 ID 확인과 페어링

토큰을 등록한 뒤에는 실제로 봇과 대화를 시작해야 합니다. 텔레그램에서 방금 만든 봇을 검색해서 들어가고, 아래처럼 입력합니다.

/start

최근 OpenClaw 텔레그램 연동 예시에서는 이 단계에서 사용자 ID와 페어링 코드가 표시되거나, 페어링용 코드가 발급되는 흐름이 자주 소개됩니다. 그런 경우 터미널에서 아래 명령으로 승인을 진행합니다.

openclaw pairing approve telegram ABCD1234

혹은 코드가 숫자 8자리처럼 보인다면 그대로 넣으면 됩니다.

openclaw pairing approve telegram 12345678

설정에 따라 표시 형식은 조금 다를 수 있지만, 핵심은 텔레그램에서 받은 페어링 코드를 OpenClaw CLI에서 승인해 연결을 마무리하는 것입니다. 이 절차가 끝나야 실제로 내 텔레그램 계정과 OpenClaw 인스턴스가 연결됩니다.

6. 토큰은 어디에 보관하는 게 안전한가

초보자는 보통 토큰을 메모장, 카카오톡 나와의 채팅, 바탕화면 텍스트 파일 같은 곳에 임시 저장해 두는 경우가 많습니다. 아주 잠깐은 그럴 수 있어도, 계속 그렇게 두는 건 좋은 습관은 아닙니다. 봇 토큰은 비밀번호와 비슷하게 생각하는 편이 안전합니다.

가장 무난한 방법은 아래 기준으로 정리하는 것입니다.

첫째, 블로그 글, 깃허브 저장소, 스크린샷 공유 이미지에 토큰이 보이지 않게 합니다.
둘째, 설정 파일에 넣었다면 그 파일 권한을 너무 넓게 열어 두지 않습니다.
셋째, 여러 곳에 복사해 둔 임시 메모는 설정 완료 후 정리합니다.
넷째, 혹시라도 유출이 의심되면 BotFather에서 토큰을 다시 발급받고 OpenClaw 설정값도 함께 갱신합니다.

실제로 최근 OpenClaw/Telegram 관련 안내에서도 토큰을 잃어버리거나 유출이 의심될 경우 BotFather에서 새 토큰으로 교체한 뒤, OpenClaw 설정에 다시 반영하는 흐름이 언급됩니다. 결국 중요한 건 “찾기 쉽게 저장”보다 “불필요하게 퍼지지 않게 저장”입니다.

7. 따라 하기용 최소 예시

처음 설정하는 사람이라면 아래 순서만 그대로 따라가도 큰 틀은 맞습니다.

# 1) 기존 게이트웨이 중지
openclaw gateway stop

# 2) 온보딩 다시 실행
openclaw onboard

# 3) Telegram (Bot API) 선택 후 토큰 입력
#    예: 123456789:AAEXAMPLE_TOKEN_REPLACE_THIS

# 4) 텔레그램에서 내 봇 검색 후 시작
#    /start

# 5) 표시된 페어링 코드 승인
openclaw pairing approve telegram ABCD1234

설정 파일로 직접 관리하고 싶다면 아래처럼 정리할 수도 있습니다.

{
  "plugins": {
    "telegram": {
      "token": "123456789:AAEXAMPLE_TOKEN_REPLACE_THIS",
      "allowedUsers": [123456789]
    }
  }
}

아쉬운 점이나 주의할 점

텔레그램 봇 생성 자체는 어렵지 않지만, 실제로 해보면 헷갈리는 부분이 몇 군데 있습니다. 대표적으로는 봇 사용자명 형식, 토큰 입력 위치, 숫자 사용자 ID와 텔레그램 아이디를 혼동하는 문제, 그리고 페어링 승인 단계를 빼먹는 경우입니다. 겉보기에는 단순한데 중간에 놓치는 포인트가 있어서, 한 번에 끝날 줄 알았다가 다시 처음부터 보는 사람도 적지 않습니다.

또 하나는 보안입니다. 개인 테스트라고 해서 토큰을 너무 가볍게 다루면 나중에 정리하기가 더 어렵습니다. 특히 블로그용 캡처 이미지나 강의 자료 화면에 토큰이 노출되는 실수는 생각보다 자주 나옵니다. 이 부분은 설정 난이도보다 습관의 문제에 가깝습니다.

정리

OpenClaw와 텔레그램을 연결할 때 핵심은 단순히 봇을 만드는 데 있지 않습니다. BotFather에서 토큰을 발급받고, OpenClaw에 정확히 입력하고, /start 이후 페어링 승인까지 마치는 것이 실제 연결의 핵심입니다. 여기에 더해 토큰을 비밀번호처럼 보관하고, 허용 사용자 ID를 제한하는 습관까지 갖춰야 안정적으로 쓸 수 있습니다.

직접 해보면 발급 과정은 금방 끝나는데, 오히려 그 뒤의 보관 방식과 승인 절차가 더 중요하게 느껴집니다. 처음 설정하는 단계라면 오늘은 우선 토큰 발급과 등록, 페어링 승인까지 정확히 끝내고, 다음 단계에서 실제 메시지 테스트와 권한 제한을 이어서 점검하는 흐름이 가장 깔끔합니다.

댓글 달기

이메일 주소는 공개되지 않습니다. 필수 필드는 *로 표시됩니다

위로 스크롤