OpenClaw를 Telegram에 연결한 뒤 가장 많이 막히는 순간은 설정을 마친 다음입니다. 토큰도 넣었고 게이트웨이도 다시 시작했는데 봇이 바로 반응하지 않으면, 어디가 잘못된 건지 감이 잘 안 잡히기 때문입니다. 처음 연동하는 사람일수록 “재시작까지 했는데 왜 답이 없지?”라는 구간에서 시간을 많이 씁니다.
실제로는 이 단계에서 무작정 재시작만 반복하기보다, 연결 확인 순서를 알고 있는 쪽이 훨씬 빠릅니다. OpenClaw 공식 문서도 Telegram 채널은 BotFather에서 만든 토큰을 설정에 넣고 게이트웨이를 시작한 뒤, 첫 DM은 pairing 목록에서 승인하는 흐름으로 안내합니다. 그래서 연동 확인은 단순히 봇에게 말을 걸어보는 수준이 아니라, 게이트웨이 상태와 pairing 상태까지 함께 보는 것이 중요합니다.
먼저 알아둘 점
Telegram은 로그인형 채널이 아니라 bot token 기반 채널입니다. 그래서 토큰을 저장한 뒤 게이트웨이를 다시 시작해야 새 설정이 반영됩니다. 공식 문서에서도 Telegram은 별도 로그인 명령을 쓰지 않고, 설정값이나 환경변수로 bot token을 넣는 방식이라고 설명합니다.
또 하나 많이 놓치는 부분은 DM 정책입니다. 기본 설정이 pairing이라면, Telegram에서 처음 보낸 메시지는 바로 처리되지 않고 승인 대기 상태로 들어갈 수 있습니다. 이 경우 사용자는 “연동이 안 된다”고 느끼지만, 실제로는 게이트웨이가 고장 난 것이 아니라 첫 연결 허용 단계가 남아 있는 것입니다. OpenClaw 문서에서도 pairing 코드는 1시간 뒤 만료된다고 안내하고 있어, 재시작 후 확인을 너무 늦게 하면 다시 점검해야 할 수 있습니다.
1단계: 게이트웨이가 실제로 살아 있는지 먼저 확인하기
제일 먼저 할 일은 Telegram을 다시 열어보는 것이 아니라, 현재 OpenClaw 게이트웨이가 정상적으로 실행 중인지 확인하는 것입니다. 연동이 안 될 때 가장 흔한 착각이 “분명 재시작했으니 실행 중일 것”이라고 생각하는 점인데, 실제로는 재시작이 제대로 반영되지 않았거나 이전 상태가 남아 있는 경우도 있습니다.
아래 명령으로 현재 상태를 먼저 확인합니다.
openclaw gateway status
공식 문서 기준으로 건강한 상태라면 runtime이 실행 중으로 보이고, RPC probe도 정상이어야 합니다. 이 단계에서 상태가 불안정하면 Telegram 쪽을 아무리 봐도 답이 안 나옵니다. 연결 확인은 늘 게이트웨이 상태부터 보는 편이 빠릅니다.
2단계: Telegram 토큰 설정이 반영됐는지 확인하기
게이트웨이가 살아 있다면, 그다음은 Telegram 토큰이 현재 설정에 실제로 들어가 있는지 보는 단계입니다. Telegram 채널은 channels.telegram.botToken 또는 token file 방식으로 설정할 수 있고, 기본 계정에서는 환경변수 fallback도 지원합니다. 그런데 사용하다 보면 토큰을 넣었다고 생각했는데 다른 설정 파일을 보고 있거나, 예전 값을 믿고 있는 경우가 꽤 많습니다.
지금 적용된 값을 확인할 때는 아래처럼 확인할 수 있습니다.
openclaw config get channels.telegram
이 단계에서는 토큰 값 전체를 굳이 화면에 오래 띄워둘 필요는 없습니다. 핵심은 Telegram 채널이 활성화돼 있는지, 관련 설정이 현재 실행 중인 게이트웨이 기준으로 들어가 있는지를 보는 것입니다. 공식 설정 문서에서도 Telegram bot token은 설정 또는 환경변수로 관리한다고 정리돼 있습니다.
3단계: 채널이 실제로 준비 상태인지 확인하기
게이트웨이가 실행 중이고 토큰 설정도 들어가 있다면, 이제는 Telegram 채널 자체가 연결 가능한 상태인지 확인해야 합니다. 이 단계가 중요한 이유는 “설정은 있음”과 “실제로 채널이 준비됨”이 다를 수 있기 때문입니다. 토큰이 맞더라도 네트워크 문제나 API 연결 문제 때문에 준비 상태가 되지 않을 수 있습니다.
이때는 아래 명령으로 채널 상태를 확인하는 편이 가장 빠릅니다.
openclaw channels status --probe
OpenClaw 공식 troubleshooting 문서도 채널 문제를 볼 때 이 명령을 먼저 확인하라고 안내합니다. Telegram 봇이 살아 있는 것처럼 보여도 여기서 ready 상태가 아니면, 실제 메시지 수신이나 응답이 제대로 되지 않을 수 있습니다.
4단계: Telegram에서 첫 DM이 pairing 대기 상태인지 보기
많이 막히는 지점이 바로 여기입니다. Telegram에서 봇에게 말을 걸었는데 아무 응답이 없으면 토큰이나 게이트웨이 문제로 생각하기 쉽지만, 실제로는 첫 DM이 pairing 승인 대기 상태인 경우가 적지 않습니다. OpenClaw Telegram 문서와 채널 troubleshooting 문서 모두, DM이 막혀 있으면 pairing 목록을 확인하라고 안내합니다.
확인할 때는 아래 명령을 사용합니다.
openclaw pairing list telegram
여기서 승인 대기 중인 항목이 보이면, 해당 코드를 승인해야 실제 대화가 열립니다.
openclaw pairing approve telegram 코드값
이 부분은 처음 연동할 때 특히 자주 놓칩니다. 사용자는 Telegram에서 이미 메시지를 보냈기 때문에 연결이 끝났다고 생각하지만, OpenClaw 쪽에서는 아직 허용되지 않은 대화로 보고 있을 수 있습니다. 공식 문서에서도 첫 DM 승인 단계를 명확히 따로 설명하고 있습니다.
5단계: 로그를 보면서 실제 메시지가 들어오는지 확인하기
앞 단계까지 다 맞는데도 반응이 없다면, 마지막으로는 로그를 보면서 Telegram에서 보낸 메시지가 OpenClaw까지 들어오는지 확인하는 것이 좋습니다. 여기서 중요한 것은 같은 메시지를 반복 전송하는 것이 아니라, 로그에 inbound 이벤트가 찍히는지, 또는 Telegram API 오류가 보이는지를 보는 것입니다.
로그 확인은 아래처럼 하면 됩니다.
openclaw logs --follow
OpenClaw 공식 troubleshooting 문서도 연결이 안 될 때 상태 확인 다음 단계로 로그 추적을 권장합니다. 만약 Telegram에서 메시지를 보냈는데 로그에 아무 inbound 흔적이 없다면, 채널 연결이나 정책 문제일 가능성이 큽니다. 반대로 메시지는 들어오는데 응답이 없다면, 라우팅이나 모델 쪽 문제까지 함께 봐야 합니다.
직접 해보면 자주 헷갈리는 부분
이 과정을 직접 해보면 가장 흔한 실수는 세 가지입니다. 첫째, 게이트웨이 재시작만 했다고 모든 설정이 자동으로 반영됐다고 믿는 경우입니다. 둘째, Telegram에서 말을 걸어놓고 pairing 승인 단계를 확인하지 않는 경우입니다. 셋째, 채널 상태를 보지 않고 바로 토큰부터 다시 만드는 경우입니다. 실제로는 새 토큰을 다시 만드는 것보다 현재 어느 단계에서 막혔는지 보는 편이 훨씬 빠릅니다.
또 하나 기억할 점은 그룹과 DM이 다를 수 있다는 점입니다. Telegram 문서에서는 그룹에서 mention requirement 같은 정책도 함께 다루고 있어서, 개인 대화에서는 되는데 그룹에서만 안 되는 경우도 충분히 생길 수 있습니다. 그래서 처음 확인은 항상 DM 기준으로 단순하게 해보고, 그다음 그룹 정책을 보는 편이 낫습니다.
연결 확인 순서는 이렇게 기억하면 편합니다
복잡하게 느껴질 때는 순서를 짧게 외우는 것이 좋습니다. 먼저 게이트웨이 상태를 보고, 그다음 Telegram 설정 반영 여부를 보고, 채널 준비 상태를 확인하고, 첫 DM pairing 여부를 보고, 마지막으로 로그를 보는 순서입니다. 이 흐름만 기억해도 같은 재시작을 몇 번씩 반복하는 실수를 줄일 수 있습니다.
실제로 OpenClaw Telegram 연동은 설정 자체보다 확인 순서를 아는 쪽이 훨씬 중요합니다. 겉보기에는 모두 “봇이 답하지 않는다”는 같은 증상처럼 보여도, 원인은 게이트웨이 실행 문제일 수도 있고, token 설정 문제일 수도 있고, pairing 승인 누락일 수도 있기 때문입니다.
정리
OpenClaw Telegram 연동 후 게이트웨이를 재시작했는데도 반응이 없을 때는, 막연히 재설치를 하기보다 확인 순서를 먼저 잡는 편이 좋습니다. 게이트웨이가 살아 있는지 확인하고, Telegram 설정이 반영됐는지 보고, 채널 상태를 확인한 뒤, 첫 DM pairing 승인과 로그까지 차례대로 보면 대부분의 문제 지점을 찾을 수 있습니다.
직접 써보면 연결 확인은 복잡한 명령을 많이 아는 것보다, 어느 단계에서 멈췄는지 구분하는 감각이 더 중요합니다. OpenClaw Telegram 연동이 잘 안 될 때도 결국 해결을 빠르게 만드는 것은 무작정 재시작하는 습관이 아니라, 재시작 뒤 무엇을 확인해야 하는지 아는 순서에 가깝습니다.