OpenClaw 설치와 텔레그램 연동 방법: DM·그룹·웹훅까지(안 될 때 진단 순서 포함)

OpenClaw 설치와 텔레그램 연동 방법: DM·그룹·웹훅까지(안 될 때 진단 순서 포함)
OpenClaw 설치와 텔레그램 연동 방법: DM·그룹·웹훅까지(안 될 때 진단 순서 포함)

 
먼저 한눈에 보기
이 글은 OpenClaw를 설치한 뒤 텔레그램 봇으로 DM/그룹에서 대화하는 흐름을 정리합니다.
처음에는 롱폴링(기본)으로 간단히 연결하고, 필요할 때만 웹훅으로 전환하는 방식이 부담이 적습니다.
DM 페어링 승인, 그룹 Privacy Mode, 멘션 반응 설정, 점검 목록과 “안 될 때” 진단 순서를 함께 제공합니다.
목차


왜 텔레그램 연동을 하나요

텔레그램 연동은 “로컬/서버에서 돌아가는 에이전트”를 “메신저로 호출”하고 싶을 때 특히 유용합니다. 외부에서 급히 확인해야 할 작업이 생기거나, 팀/개인 작업 로그를 텔레그램에서 주고받고 싶을 때 진입 장벽이 낮습니다.

실무에서 자주 나오는 패턴
가장 흔한 시행착오는 “DM은 되는데 그룹이 조용한 경우”입니다. 이때는 대개 멘션 반응 설정이나 Privacy Mode가 원인인 경우가 많아, 그룹 테스트는 @멘션부터 시작하면 시간을 아낄 수 있습니다.

설치 전 준비

  • Node.js 22 이상
  • OpenClaw CLI 설치 권한(로컬 PC 또는 서버)
  • 텔레그램 계정 + BotFather로 발급한 봇 토큰
참고
Windows는 WSL2 환경이 권장되는 경우가 많습니다. 설치 환경이 복잡하면 먼저 “로컬에서 성공 → 서버로 이전” 순서를 추천합니다.

설치·연동 순서

설치

# 전역 설치(대안 중 하나)
npm install -g openclaw@latest

# 온보딩 + 서비스(데몬) 설치
openclaw onboard --install-daemon

첫 실행 확인

# 서비스가 이미 떠 있는지 확인
openclaw gateway status

# 디버깅용(포그라운드 실행 + 로그 확인)
openclaw gateway --port 18789 --verbose
빠른 확인 명령
설치 후 전체 상태를 한 번에 확인하려면 아래처럼 “상태/헬스”부터 보는 편이 빠릅니다. 
openclaw status
openclaw health

토큰 발급

  1. 텔레그램에서 @BotFather와 대화 시작
  2. /newbot 입력 → 이름/username 설정(보통 bot로 끝남)
  3. 발급된 토큰을 안전하게 보관

설정 반영

토큰은 환경변수로도 가능하지만, 운영/재현성을 생각하면 설정 파일 방식이 깔끔합니다. (환경변수와 설정이 동시에 있으면, 설정이 우선 적용되는 구성이 일반적입니다.) 

# (옵션 A) 환경변수
# macOS/Linux
export TELEGRAM_BOT_TOKEN="123:abc"

# Windows PowerShell
setx TELEGRAM_BOT_TOKEN "123:abc"

설정 파일(예: ~/.openclaw/openclaw.json) 예시:

{
  "channels": {
    "telegram": {
      "enabled": true,
      "botToken": "123:abc",
      "dmPolicy": "pairing",
      "groups": { "*": { "requireMention": true } }
    }
  }
}

첫 테스트

1) 게이트웨이를 실행한 뒤 2) 텔레그램에서 봇에게 DM을 보내세요. 처음 DM은 페어링 코드 승인이 필요할 수 있어, 안내가 뜨면 승인 절차를 완료합니다.

운영 초반 기본값
그룹은 requireMention을 켠 상태로 시작하면, 의도치 않은 반응(소음)을 크게 줄일 수 있습니다.

그룹에서 봇이 조용할 때

그룹에서 반응이 없을 때는 “봇이 메시지를 받지 못하는 상황”과 “받지만 반응 조건이 맞지 않는 상황”으로 나누어 보면 진단이 쉬워집니다.

가장 먼저 해볼 것
그룹에서 @봇아이디를 붙여 멘션 테스트를 해보세요. 멘션에만 반응한다면 멘션 반응 설정이 원인일 가능성이 높습니다.
Privacy Mode 관련
텔레그램 봇은 기본적으로 Privacy Mode가 켜져 그룹 메시지 수신이 제한될 수 있습니다. 필요하다면 BotFather에서 /setprivacy를 조정하거나, 봇을 그룹 관리자 권한으로 올리는 방식을 검토할 수 있습니다. 설정을 바꾼 뒤에는 그룹에서 봇을 제거했다가 다시 초대해야 적용되는 경우가 있습니다.

웹훅 전환 전 확인

웹훅은 “텔레그램이 내 서버로 푸시”해주는 방식이라, 네트워크/HTTPS/프록시 같은 운영 변수가 늘어납니다. 서버 상시 운영이 필요하거나, 환경상 롱폴링이 불리할 때만 전환하는 편이 안전합니다.

전환 전에 점검할 것
1) 외부에서 접근 가능한 HTTPS가 준비되어 있는지
2) 리버스 프록시(예: Nginx/Caddy)에서 경로 매핑이 명확한지
3) 시크릿/토큰이 로그에 노출되지 않는지

점검 목록

복사용 점검 목록
  • [ ] Node.js 22 이상이다.
  • [ ] openclaw onboard --install-daemon를 실행했고, gateway가 동작한다.
  • [ ] 텔레그램 토큰을 설정(환경변수 또는 설정 파일)했고, gateway 재시작까지 했다.
  • [ ] DM에서 첫 대화 후 페어링 승인 흐름이 완료되었다.
  • [ ] 그룹에서는 멘션 테스트로 1차 확인했다(@봇아이디).
  • [ ] Privacy Mode 변경 시 그룹에서 봇 재초대까지 진행했다(필요한 경우).
  • [ ] 운영 초반은 requireMention 기본값으로 소음을 줄였다.

진단 순서

DM이 무반응일 때

  1. 토큰 값(오타/공백/따옴표)을 다시 확인
  2. channels.telegram.enabled가 true인지 확인
  3. 게이트웨이 재시작(설정 변경 반영)
  4. openclaw gateway --port 18789 --verbose로 로그 확인
  5. 페어링 승인(요청이 뜨는지 확인)

그룹이 무반응일 때

  1. 멘션 테스트(멘션에 반응하는지)
  2. Privacy Mode 상태 확인 및 필요 시 조정
  3. Privacy Mode 조정 후 그룹에서 봇 제거/재초대
  4. 그룹 권한(관리자 여부) 검토
  5. requireMention 설정값 재확인

전체가 불안정할 때

  1. openclaw health로 상태 점검
  2. 최근 설정 변경 사항을 되돌린 뒤(원복) 다시 확인
  3. 보안 점검(권한/노출 범위/토큰 관리) 재정비

안전 운영 기본

안전 안내
토큰/키가 유출되면 즉시 재발급이 필요합니다. 또한 확장 기능(스킬)은 실행 권한을 가질 수 있어, 운영 환경에서는 “필요 최소 + 출처 확인 + 권한 최소화” 원칙으로 접근하는 편이 안전합니다.
권장 운영 흐름
1) DM은 페어링 정책을 유지하고
2) 그룹은 멘션 반응을 기본값으로 두며
3) 필요한 그룹/사용자만 점진적으로 허용하는 방식이 사고를 줄입니다.
보안 점검 습관
환경을 바꾸거나(서버 이전/웹훅 전환 등) 노출 범위를 넓혔다면, 보안 점검 명령을 한 번 실행해 보는 습관이 도움이 됩니다. 
openclaw security audit --deep

FAQ

질문을 누르면 답변이 펼쳐집니다.

Q1. 설치에 꼭 Node 22 이상이 필요한가요?
A. 공식 시작 가이드에서 Node 22 이상을 전제로 안내하는 경우가 많습니다. 버전이 낮으면 설치는 되더라도 실행 단계에서 예기치 않은 오류가 생길 수 있어요.
Q2. 가장 단순한 설치 흐름은 무엇인가요?
A. 전역 설치(npm install -g openclaw@latest) 후 온보딩(openclaw onboard --install-daemon)이 가장 단순합니다. 온보딩이 기본 설정을 잡아주는 역할을 합니다.
Q3. 설치 후 정상 동작을 빠르게 확인하려면 무엇부터 보나요?
A. openclaw status와 openclaw health로 1차 점검을 하고, 필요하면 openclaw gateway --verbose로 로그를 확인하는 순서가 빠릅니다.
Q4. 텔레그램 토큰은 환경변수와 설정 파일 중 무엇이 더 좋나요?
A. 빠른 테스트는 환경변수가 편하지만, 운영/재현성을 생각하면 설정 파일이 더 깔끔합니다. 동시에 설정되어 있다면 설정 파일이 우선 적용되는 구성이 일반적입니다.
Q5. 설정을 바꿨는데 반영이 안 되는 것 같아요.
A. 보통 게이트웨이(또는 데몬)를 재시작해야 변경 사항이 반영됩니다. 반영 후에는 DM/그룹에서 간단한 테스트 메시지로 확인해 주세요.
Q6. 그룹에서 봇이 반응하지 않으면 무엇부터 확인하나요?
A. 먼저 @봇아이디 멘션으로 테스트해 보세요. 멘션에는 반응하지만 일반 메시지에는 반응하지 않는다면 멘션 반응 설정이 원인일 가능성이 큽니다.
Q7. Privacy Mode는 왜 문제가 되나요?
A. Privacy Mode가 켜져 있으면 봇이 그룹 메시지를 제한적으로만 수신할 수 있습니다. 필요하면 BotFather 설정 조정이나 관리자 권한 부여를 검토하세요.
Q8. Privacy Mode를 바꿨는데도 그대로예요.
A. 설정 변경 후에는 그룹에서 봇을 제거했다가 다시 초대해야 적용되는 경우가 있습니다. 적용이 의심되면 재초대 후 멘션 테스트로 다시 확인해 주세요.
Q9. 그룹에서 멘션 반응을 기본값으로 두는 이유가 있나요?
A. 모든 메시지에 반응하면 소음이 커지고 의도치 않은 응답이 늘 수 있습니다. 운영 초반은 멘션 반응으로 시작해 안정화한 뒤 범위를 넓히는 편이 좋습니다.
Q10. 봇을 그룹 관리자 권한으로 올리면 무엇이 달라지나요?
A. 일부 환경에서는 메시지 수신 범위가 넓어져 동작이 개선될 수 있습니다. 다만 권한이 커지는 만큼 운영 정책(멘션/허용 범위)을 함께 정리하는 편이 안전합니다.
Q11. 텔레그램 연동은 기본이 롱폴링인가요?
A. 텔레그램 채널은 롱폴링이 기본이고 웹훅은 선택인 경우가 많습니다. 처음에는 공개 URL 없이 되는 롱폴링으로 안정화하는 편이 부담이 적습니다.
Q12. 웹훅 전환을 고려해야 하는 경우는 언제인가요?
A. 서버 상시 운영이 필요하거나, 환경상 롱폴링이 불리할 때 웹훅을 검토합니다. 다만 HTTPS/프록시/방화벽 등 운영 변수가 늘어나는 점은 감안해야 합니다.
Q13. 웹훅에서 가장 흔한 실패 원인은 무엇인가요?
A. HTTPS 인증서 문제(만료/체인), 프록시 경로 매핑 불일치, 방화벽 차단, 시크릿/토큰 설정 누락이 흔합니다. “외부에서 HTTPS로 접근 가능한가”부터 확인하면 진단이 빨라집니다.
Q14. 웹훅으로 바꾸면 무조건 더 빠르나요?
A. 상황에 따라 다릅니다. 롱폴링도 충분히 빠르고 운영이 단순한 장점이 있으며, 웹훅은 운영 요소가 늘어나는 대신 푸시 방식의 이점을 얻는 구조입니다.
Q15. 웹훅 전환 전에 최소 점검 3가지만 꼽는다면요?
A. (1) 외부 HTTPS 접근 가능 여부, (2) 프록시 경로/포트 매핑 일치, (3) 토큰·시크릿이 로그에 노출되지 않는지 점검을 우선 추천합니다.
Q16. DM 페어링 승인은 왜 필요한가요?
A. DM을 “승인된 사용자”로 제한해 임의의 접근을 줄이기 위한 안전장치입니다. 운영 환경에서는 페어링 정책을 유지하는 편이 안전합니다.
Q17. 토큰이 유출된 것 같으면 어떻게 해야 하나요?
A. BotFather에서 토큰을 재발급하고, 설정을 새 토큰으로 교체한 뒤 게이트웨이를 재시작해 주세요. 유출 가능성이 있는 저장소/로그도 함께 점검하는 편이 좋습니다.
Q18. 토큰을 안전하게 관리하는 요령이 있나요?
A. 공개 저장소에 남기지 않고, 환경변수 관리 도구나 비공개 설정 저장소를 사용하세요. 운영 전에는 “로그/화면에 토큰이 출력되지 않는지” 점검하는 습관이 도움이 됩니다.
Q19. 확장 기능(스킬)을 설치할 때 무엇을 확인해야 하나요?
A. 출처(공식/검증된 배포처), 코드/변경 이력, 필요한 권한 범위를 확인하고 가능하면 격리 환경에서 먼저 테스트하는 편이 안전합니다. 필요 최소 설치가 기본 원칙입니다.
Q20. 운영 중 불안정해지면 어떤 순서로 안전 조치하나요?
A. 먼저 노출 범위를 줄이고(그룹 반응 제한/서비스 중지 포함), 토큰을 교체한 뒤, 로그와 보안 점검을 통해 원인을 확인하는 흐름이 안전합니다. 상황이 정리되면 단계적으로 다시 켜는 편을 권합니다.
최종 업데이트: 2026-02-04

참고 자료

이 블로그의 인기 게시물

겨울철 차량 시동 안 걸릴 때 대처법 총정리

이미지
겨울철 차량 시동 안 걸릴 때 대처법 총정리 📋 목차 겨울철 시동 불량 원인 배터리 관리법 🔋 엔진오일과 연료 관리법 🛢️ 시동 전 예열 습관 🚗 시동 안 걸릴 때 대처법 🧰 겨울철 차량 준비물 체크리스트 🧤 FAQ ❄️ 겨울만 되면 차량 시동이 쉽게 안 걸려서 당황한 경험, 한 번쯤은 있지 않으셨나요? 특히 아침에 급히 출근하려는 순간 시동이 안 걸리면 하루 시작부터 고생이죠. 기온이 영하로 떨어지는 겨울에는 차량의 여러 시스템이 평소보다 더 큰 영향을 받아요. 이번 포스팅에서는 겨울철 시동 불량의 주요 원인을 알아보고, 이를 예방할 수 있는 실질적인 관리 팁을 하나씩 알려드릴게요. 자동차 초보자도 쉽게 따라 할 수 있도록 표와 함께 정리했어요. 제가 생각했을 때 이건 겨울 운전자의 필수 상식이라고 봐요! 🚘 🧊 겨울철 시동 불량 원인 기온이 급격히 떨어지면 차량 내부 시스템들이 제 역할을 하지 못해 시동이 어려워져요. 대표적인 원인은 배터리 방전, 엔진오일 점도 변화, 연료 공급 문제 등인데요. 추운 날씨에는 연료 분사도 늦고, 엔진 윤활이 원활하지 않아 시동에 시간이 더 걸리게 돼요.  또한 노후 차량의 경우 배터리 성능 저하나 연료 필터에 수분이 응결되는 등의 문제가 함께 겹치면 시동이 아예 걸리지 않는 상황도 생겨요. 예열 플러그가 고장 났거나 점화 플러그 상태가 나쁘면 아무리 시동을 걸어도 반응이 없을 수 있답니다.  현대 차량들은 전자장치 비중이 높아 전압 저하가 심하면 ECU가 제대로 작동하지 않아 엔진이 돌지 않아요. 추운 날씨에 오래 주차된 차량은 배터리 자체가 냉각돼 전력 공급이 매우 낮아지기도 하죠.  이런 문제를 사전에 막으려면 원인을 정확히 이해하고, 각 부분을 꼼꼼히 관리해야 해요. 아래 표를 통해 대표적인 시동 불량 원인과 해결책을 한...
Read more »

가정에서 감자 오래 보관하는 방법 (냉장보관, 여름/겨울철 보관, 껍찔째 보관, 양파와 함께)

이미지
가정에서 감자 오래 보관하는 방법 (냉장보관, 여름/겨울철 보관, 껍찔째 보관, 양파와 함께) 📋 목차 감자의 역사와 기원 감자의 영양 성분과 효능 감자 오래 보관하는 기본 원칙 냉장고 보관 시 주의사항 최신 감자 저장 기술과 트렌드 실생활 감자 관리 꿀팁 FAQ 감자는 전 세계적으로 사랑받는 식재료예요. 한국에서도 국, 찌개, 반찬, 간식까지 다양한 음식에 활용되고 있어요. 하지만 감자는 보관 방법을 잘못 선택하면 쉽게 싹이 트거나 무르게 변해 버리죠.   최신 연구와 생활 지혜를 바탕으로, 감자를 오래 두고 신선하게 먹을 수 있는 방법들을 소개할게요. 또한 표와 사례를 통해 더 이해하기 쉽게 정리했어요.   저는 개인적으로 감자를 자주 먹는 편인데, 제가 생각했을 때 올바른 보관법을 아는 게 정말 중요하더라고요. 작은 습관 하나가 맛과 건강을 모두 지켜주기 때문이에요. 그럼 이제 본격적으로 감자의 보관 꿀팁을 알아볼까요? 🥔✨   🥔 감자의 역사와 기원 감자는 약 7천 년 전 남아메리카 안데스 산맥에서 처음 재배되기 시작했어요. 페루와 볼리비아 지역에서 발견된 고대 유물 속에서도 감자의 흔적을 찾을 수 있는데, 이는 인류가 오랜 세월 동안 감자를 주요 식량으로 삼아왔다는 걸 보여줘요. 🌍   안데스 지역 원주민들은 감자를 단순히 음식으로만 사용한 것이 아니라 의학적, 종교적 의식에도 활용했다고 해요. 고산 지대 특유의 기후 덕분에 감자는 다양한 품종으로 발달했고, 지금 우리가 먹는 수천 가지 품종의 기반이 되었죠.   16세기 스페인 탐험가들이 신대륙을 발견한 뒤 감자를 유럽으로 가져왔고, 이후 전 세계로 퍼지게 되었어요. 초창기 유럽에서는 감자가 독이 있는 작물이라며 기피했지만, 기근과 전쟁 시기마다 사람들의 생명을 구하는 중요한 식량이 되...
Read more »

김치냉장고 없이 김치 빨리 익히는 법 (김치 오래 보관하는 법)

이미지
김치냉장고 없이 김치 빨리 익히는 법 (김치 오래 보관하는 법) 📋 목차 김치 발효와 역사적 배경 발효가 빨라지는 과학적 원리 온도와 환경 관리 요령 재료와 양념 비율 최적화 김치 빠른 숙성 꿀팁 보관 방법과 맛 유지법 FAQ 김치는 한국을 대표하는 발효 음식으로, 시간이 지나야 제대로 익어 깊은 맛을 내요. 하지만 요즘처럼 바쁜 생활 속에서는 김치를 빨리 숙성시켜 먹고 싶을 때가 많죠. 사실 발효의 원리를 잘 이해하면 시간을 단축하면서도 맛을 놓치지 않고 김치를 즐길 수 있어요.   특히 2025년 현재, 가정용 김치냉장고의 다양한 숙성 모드와 미생물 연구를 통한 발효 촉진 방법들이 소개되고 있어요. 제가 보기엔 이 변화가 김치 문화의 현대적 진화를 잘 보여주는 것 같아요. 아래에서 구체적인 방법들을 차근차근 정리해 드릴게요.   🥬 김치 발효와 역사적 배경 김치는 오랜 세월 동안 한국인의 밥상에서 빠질 수 없는 음식이었어요. 발효 과정은 단순히 맛을 내기 위한 과정이 아니라, 저장과 보존을 가능하게 해주는 지혜였답니다. 특히 겨울철 긴 저장 기간 동안 채소를 오래 보관하기 위해 소금 절임과 발효 기술이 발달했어요. 시간이 지나면서 김치는 단순히 저장용 음식이 아니라, 고유의 풍미와 영양 가치를 가진 전통 발효식품으로 자리 잡았어요.   삼국시대 기록에도 김치의 원형이 보이고, 조선시대에 들어오면서 고추가 전래되자 매운맛이 더해졌어요. 이때부터 오늘날 우리가 먹는 빨간 김치가 본격적으로 자리 잡기 시작했죠. 즉, 김치의 발효는 역사와 문화, 그리고 생존을 위한 지혜가 녹아 있는 과정이라고 볼 수 있어요.   사람들이 흔히 김치는 오래 두어야 제맛이 난다고 생각하지만, 사실 기온과 환경에 따라 발효 속도는 크게 달라져요. 여름철에는 금방 익어버리고, 겨울철...
Read more »