OpenClaw를 텔레그램과 연결할 때 처음 막히는 지점은 봇 생성보다도 dmPolicy와 pairing 설정입니다. 봇 토큰만 넣으면 바로 대화가 될 것 같지만, 실제로는 누가 봇에게 메시지를 보낼 수 있는지, 처음 접근한 사용자를 어떤 방식으로 승인할지까지 함께 이해해야 제대로 동작합니다.
특히 이 부분을 모르고 시작하면 “분명 연결은 된 것 같은데 봇이 답을 안 한다”는 상황이 자주 생깁니다. 실제로는 토큰이 틀린 게 아니라 접근 정책 때문에 응답이 막혀 있는 경우가 많습니다. 그래서 OpenClaw Telegram 연동은 단순 연결보다 DM 허용 방식을 먼저 이해하는 게 더 중요합니다.
먼저 알아둘 점
dmPolicy는 텔레그램 DM에서 누가 봇과 대화할 수 있는지 정하는 설정입니다. 쉽게 말해 개인 채팅 접근 정책이라고 보면 됩니다. 여기서 많이 쓰는 값이 pairing과 allowlist입니다.
pairing은 처음 봇에게 DM을 보내는 사용자를 바로 허용하지 않고, 한 번 승인 절차를 거치게 하는 방식입니다. 반면 allowlist는 미리 등록해 둔 특정 사용자만 접근할 수 있게 막아두는 설정입니다. 혼자 쓰는 개인용 봇이라면 allowlist가 관리하기 편한 경우가 많고, 처음 테스트할 때는 pairing이 이해하기 쉽습니다.
이 둘은 비슷해 보이지만 운영 방식이 꽤 다릅니다. pairing은 처음 연결할 때는 편하지만 승인 절차를 알아야 하고, allowlist는 처음 설정이 조금 번거롭지만 이후에는 누가 쓸 수 있는지 훨씬 분명합니다.
1단계: Telegram에서 봇 만들기
가장 먼저 할 일은 텔레그램에서 봇을 만드는 것입니다. 텔레그램 앱에서 @BotFather를 검색한 뒤 대화를 열고 아래 명령을 입력합니다.
/newbot이후 안내에 따라 봇 이름과 사용자명을 정하면 Bot Token이 발급됩니다. 이 토큰은 OpenClaw가 텔레그램 봇으로 접속할 때 사용하는 값입니다.
여기서 주의할 점은 토큰을 절대 외부에 노출하면 안 된다는 것입니다. 블로그 글 작성용 예시를 만들 때도 실제 토큰을 그대로 넣지 말고 반드시 예시 문자열로 바꿔야 합니다.
2단계: OpenClaw 설정 파일에 Telegram 채널 추가하기
처음 테스트할 때 가장 무난한 방식은 dmPolicy를 pairing으로 두는 것입니다. 아래 예시는 가장 기본적인 Telegram 연결 설정입니다.
{
"channels": {
"telegram": {
"enabled": true,
"botToken": "YOUR_BOT_TOKEN",
"dmPolicy": "pairing",
"groups": {
"*": {
"requireMention": true
}
}
}
}
}이 설정에서 중요한 부분은 네 가지입니다.
첫째, enabled는 Telegram 채널을 켜는 항목입니다. 둘째, botToken에는 BotFather에서 받은 토큰을 넣습니다. 셋째, dmPolicy: "pairing"은 첫 DM 사용자에게 승인 절차를 요구한다는 뜻입니다. 넷째, requireMention: true는 그룹방에서 아무 말에나 반응하지 않고, 봇을 멘션했을 때만 반응하게 만드는 안전장치입니다.
처음에는 이 정도만 넣고 시작해도 충분합니다. 괜히 여러 옵션을 한 번에 건드리면 어디서 막히는지 파악하기 어려워집니다.
3단계: gateway 실행 후 pairing 승인하기
설정 파일을 저장했다면 이제 OpenClaw gateway를 실행합니다.
openclaw gateway그다음 텔레그램에서 방금 만든 봇에게 아무 메시지나 하나 보냅니다. 예를 들어 아래처럼 보내면 됩니다.
hi이 시점에서 pairing 정책을 사용 중이라면, 봇이 바로 답을 하지 않을 수 있습니다. 이게 실패가 아니라 정상 동작일 때가 많습니다. 아직 사용자가 승인되지 않았기 때문입니다.
이제 터미널에서 pairing 요청을 확인합니다.
openclaw pairing list telegram그러면 승인 대기 중인 코드가 보이는데, 그 코드를 이용해 아래처럼 승인합니다.
openclaw pairing approve telegram <PAIRING_CODE>이 과정을 마치면 해당 사용자는 봇과 실제로 대화할 수 있게 됩니다. 처음 설치할 때 많은 분들이 여기서 막힙니다. 토큰 문제로 생각하기 쉽지만, 실제로는 pairing 승인을 안 해서 생기는 경우가 많습니다.
4단계: 계속 혼자 쓸 거라면 allowlist가 더 편할 수 있다
처음 테스트는 pairing으로 해도 괜찮지만, 혼자 오래 쓸 개인용 봇이라면 나중에는 allowlist로 바꾸는 편이 관리하기 수월한 경우가 많습니다. 이유는 간단합니다. 누가 접근 가능한지 설정 파일에 명확하게 남기기 때문입니다.
예시는 아래처럼 구성할 수 있습니다.
{
"channels": {
"telegram": {
"enabled": true,
"botToken": "YOUR_BOT_TOKEN",
"dmPolicy": "allowlist",
"allowFrom": ["tg:123456789"]
}
}
}여기서 123456789 자리에 들어가는 값은 내 텔레그램 숫자 사용자 ID입니다. 이 값을 알아내야 allowlist를 제대로 쓸 수 있습니다.
내 Telegram 숫자 ID 확인하는 방법
처음 접하는 분들은 보통 사용자명과 숫자 ID를 헷갈립니다. allowlist에 넣어야 하는 것은 보통 숫자형 사용자 ID입니다. 가장 단순한 방법은 봇에게 직접 메시지를 보낸 뒤 로그를 확인하는 것입니다.
openclaw logs --follow이 상태에서 텔레그램으로 봇에게 메시지를 보내면 로그에 사용자 정보가 찍히고, 그 안의 from.id 값을 확인할 수 있습니다. 이 숫자를 allowFrom에 넣으면 됩니다.
예를 들어 로그에서 from.id가 987654321로 보였다면 설정은 이렇게 바꿀 수 있습니다.
{
"channels": {
"telegram": {
"enabled": true,
"botToken": "YOUR_BOT_TOKEN",
"dmPolicy": "allowlist",
"allowFrom": ["tg:987654321"]
}
}
}이 방식은 한 번 세팅해 두면 pairing 승인 절차 없이도 지정한 사용자만 안정적으로 접근할 수 있다는 점이 장점입니다.
직접 써보면 헷갈리는 부분
가장 많이 헷갈리는 건 “연결 성공”과 “실제 대화 가능”이 다르다는 점입니다. gateway가 정상 실행되고 토큰도 맞는데 답장이 안 오면 보통 설정을 처음부터 다시 보게 됩니다. 하지만 실제 원인은 접근 정책인 경우가 더 많습니다.
또 하나는 pairing이 영구 허용처럼 느껴진다는 점입니다. 처음 승인을 해두면 계속 될 것 같지만, 운영 방식이나 환경에 따라 다시 확인이 필요한 경우도 있습니다. 반면 allowlist는 누가 쓸 수 있는지 분명하다는 장점이 있지만, 숫자형 ID를 정확히 넣어야 해서 처음에는 조금 더 번거롭게 느껴집니다.
직접 써보면 초보자에게는 pairing이 직관적이고, 혼자 장기적으로 운영할 때는 allowlist가 더 깔끔하게 느껴질 가능성이 큽니다. 어떤 방식이 더 낫다고 단정하기보다는, 테스트 단계와 실제 운영 단계를 나눠 생각하는 편이 현실적입니다.
그룹방까지 연동할 때 주의할 점
개인 DM만 연결할 때보다 그룹방은 조금 더 복잡합니다. 특히 그룹에 봇을 넣었다고 해서 바로 모든 메시지에 반응하는 것은 아닙니다. 기본적으로는 멘션이 필요하도록 두는 편이 안전합니다.
예를 들어 특정 그룹에서만 반응하게 하고 싶다면 아래처럼 시작할 수 있습니다.
{
"channels": {
"telegram": {
"enabled": true,
"botToken": "YOUR_BOT_TOKEN",
"groups": {
"-1001234567890": {
"groupPolicy": "open",
"requireMention": false
}
}
}
}
}다만 실제 운영에서는 requireMention을 꺼두면 그룹에서 너무 자주 반응해 불편해질 수 있습니다. 처음에는 멘션이 있을 때만 반응하도록 두고, 필요하면 나중에 완화하는 편이 낫습니다.
또 텔레그램 봇은 그룹 메시지 가시성과 관련된 설정도 영향을 줄 수 있어서, 봇이 그룹에서 예상대로 반응하지 않으면 OpenClaw 설정만 보지 말고 텔레그램 쪽 봇 설정도 함께 점검해야 합니다.
바로 따라할 수 있는 최소 설정 예시
처음 테스트용이라면 아래 구성으로 시작하는 것이 가장 단순합니다.
{
"channels": {
"telegram": {
"enabled": true,
"botToken": "YOUR_BOT_TOKEN",
"dmPolicy": "pairing"
}
}
}openclaw gateway
openclaw pairing list telegram
openclaw pairing approve telegram <PAIRING_CODE>혼자 계속 사용할 개인용 봇이라면 아래처럼 바꾸는 방식이 더 편할 수 있습니다.
{
"channels": {
"telegram": {
"enabled": true,
"botToken": "YOUR_BOT_TOKEN",
"dmPolicy": "allowlist",
"allowFrom": ["tg:YOUR_NUMERIC_TELEGRAM_USER_ID"]
}
}
}아쉬운 점이나 주의할 점
OpenClaw Telegram 연동은 겉으로 보면 쉬워 보이지만, 실제로는 “봇 생성 → 토큰 입력”으로 끝나는 작업이 아닙니다. 특히 초보자 입장에서는 봇이 왜 답을 안 하는지 원인을 바로 찾기 어렵습니다. 봇 토큰 문제인지, pairing 미승인인지, allowlist 값이 틀린 건지, 그룹 정책 때문인지 하나씩 확인해야 합니다.
그래서 처음에는 기능을 많이 넣지 말고 최소 설정으로 시작하는 게 좋습니다. 개인 DM 연결만 먼저 확인하고, 그다음 allowlist 전환, 마지막에 그룹 반응까지 단계적으로 붙이는 방식이 훨씬 덜 헷갈립니다.
정리
OpenClaw Telegram 연동의 핵심은 단순히 봇을 만드는 것이 아니라, 누가 접근 가능한지를 dmPolicy로 정하는 데 있습니다. 빠르게 테스트하려면 pairing이 편하고, 혼자 오래 쓸 봇이라면 allowlist가 더 관리하기 좋습니다.
실제로 따라할 때는 먼저 pairing으로 연결이 되는지 확인하고, 이후 내 Telegram 숫자 ID를 확인해서 allowlist로 전환하는 순서가 가장 무난합니다. 이 흐름만 이해하면 OpenClaw Telegram 연동에서 가장 헷갈리는 부분은 대부분 정리됩니다.