OpenClaw를 텔레그램에 연동할 때 가장 많이 겪는 상황은 “설정은 다 한 것 같은데 아무 반응이 없는 경우”다. 토큰도 넣었고, 봇도 만들었고, 명령어도 보냈는데 조용한 상태가 계속된다.
이때 많은 사람들이 하는 행동이 있다. 명령어를 바꿔보거나, 설정 파일을 다시 뒤집어보거나, 심지어 토큰을 다시 발급받기도 한다. 그런데 실제로는 문제를 잘못 짚고 있어서 시간이 더 길어지는 경우가 많다.
OpenClaw와 텔레그램 연동 오류는 대부분 몇 가지 패턴 안에서 반복된다. 중요한 건 “무엇이 문제인지 많이 아는 것”보다, “어디부터 확인해야 하는지”를 아는 것이다.
이 글에서는 실제로 자주 발생하는 오류를 단계별로 나누고, 시간을 덜 쓰는 점검 순서를 기준으로 정리해본다.
먼저 알아둘 점
연동 문제는 크게 세 구간으로 나눌 수 있다. 메시지가 아예 서버까지 도달하지 않는 경우, 메시지는 들어오지만 처리되지 않는 경우, 그리고 처리까지 됐지만 응답이 나가지 않는 경우다.
이 세 단계를 구분하지 않으면 계속 엉뚱한 부분만 수정하게 된다. 예를 들어 메시지가 아예 안 들어오는데 명령어 코드를 수정하는 식이다. 그래서 가장 먼저 해야 할 건 “지금 어디까지는 정상인지”를 확인하는 것이다.
1단계. OpenClaw가 실제로 실행 중인지 확인
가장 기본이지만 가장 많이 놓치는 부분이다. 서버가 꺼져 있거나, 실행 중간에 에러로 종료된 상태라면 텔레그램에서는 아무 반응이 없는 게 정상이다.
ps aux | grep openclaw
프로세스가 보이지 않는다면, 연동 문제가 아니라 실행 문제다. 특히 재부팅 이후 자동 실행이 안 되는 경우도 자주 발생한다.
이 단계에서 막혔다면 이후 설정을 아무리 수정해도 의미가 없다.
2단계. Telegram 토큰이 실제로 유효한지 확인
토큰 오류는 생각보다 빈도가 높다. 복사 과정에서 공백이 들어가거나, 일부 문자열이 잘리는 경우가 많다. 또는 예전에 발급받은 토큰을 그대로 쓰고 있는 경우도 있다.
TELEGRAM_BOT_TOKEN=123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11
토큰이 틀리면 보통은 명확한 에러 없이 조용히 실패하는 경우가 많아서 더 헷갈린다. 의심되면 재발급해서 교체하는 게 빠르다.
3단계. webhook과 polling을 동시에 쓰고 있지 않은지 확인
이건 구조를 이해하지 않으면 계속 막히는 부분이다. 텔레그램 봇은 webhook 방식과 polling 방식을 동시에 사용할 수 없다.
# polling
app.run_polling()
# webhook
app.run_webhook(...)
둘 다 설정되어 있으면 메시지가 정상적으로 처리되지 않는다. 특히 기존 설정을 남겨둔 상태에서 다른 방식을 추가할 때 이런 문제가 자주 발생한다.
4단계. 메시지가 서버까지 들어오는지 로그로 확인
이 단계가 핵심이다. 실제로는 많은 사람들이 이걸 건너뛴다. 하지만 이걸 확인하면 문제의 절반은 바로 구분된다.
[INFO] update received
이 로그가 없다면 텔레그램 → 서버 연결이 안 된 것이다. webhook 설정, 포트, 방화벽, URL 등을 먼저 의심해야 한다.
반대로 이 로그가 찍힌다면, 최소한 메시지는 들어오고 있다는 뜻이다. 이 경우부터는 코드 쪽을 보면 된다.
5단계. chat_id 필터 때문에 막히는 경우
OpenClaw에서 특정 채팅만 허용하도록 설정한 경우, 다른 채팅에서는 아무 반응이 없다. 특히 개인 채팅과 그룹을 번갈아 테스트할 때 자주 헷갈린다.
if chat_id not in ALLOWED_CHAT_IDS:
return
이 상태에서는 로그는 찍히지만 응답이 없는 것처럼 보인다. 그래서 “명령이 안 된다”고 착각하기 쉽다.
6단계. 명령어 파싱 조건이 실제 입력과 맞는지 확인
메시지는 들어오는데 반응이 없다면, 대부분 이 단계다. 특히 그룹에서는 멘션이 붙거나, 공백이 포함되면서 조건이 어긋나는 경우가 많다.
if text.startswith("/status"):
return "OK"
예를 들어 /status@botname 형태로 들어오면 위 조건은 실패한다. 이런 부분은 직접 로그를 보고 확인하는 게 가장 정확하다.
7단계. 응답은 생성되지만 전송 실패하는 경우
이건 겉으로 보기에는 “아무 반응 없음”과 똑같이 보이지만, 실제로는 다른 문제다.
[ERROR] 403 Forbidden
이 경우는 권한 문제거나, 봇이 해당 채팅에서 차단된 상태일 수 있다. 특히 그룹에서 권한이 부족할 때 자주 발생한다.
8단계. 개인 채팅 vs 그룹 채팅 동작 차이
같은 코드인데 개인 채팅에서는 되고 그룹에서는 안 되는 경우가 있다. 이건 대부분 privacy mode나 멘션 처리 방식 때문이다.
그래서 테스트는 항상 개인 → 그룹 순서로 진행하는 게 좋다. 처음부터 그룹에서 테스트하면 원인 파악이 더 어려워진다.
9단계. 로그를 안 보고 감으로 수정하는 경우
가장 오래 걸리는 패턴이다. 명령어를 바꾸거나 설정을 계속 건드리지만, 실제 문제 위치는 전혀 다른 곳에 있는 경우가 많다.
[INFO] update received
[INFO] command matched
[INFO] response sent
이 흐름 중 어디까지 찍히는지만 봐도 문제 위치는 거의 확정된다. 이걸 안 보면 계속 같은 자리에서 반복하게 된다.
직접 써보면 헷갈리는 부분
겉으로 보이는 증상은 대부분 비슷하다. “명령을 보내도 아무 반응이 없다”는 한 문장으로 정리된다. 하지만 실제 원인은 완전히 다르다.
그래서 많은 사람들이 명령어 문제로 착각하거나, 반대로 코드 문제를 텔레그램 설정 문제로 오해한다. 특히 webhook 문제는 코드 문제처럼 보이기 쉽다.
이 순서대로 보면 가장 빠르게 해결된다
실제 기준으로는 아래 순서가 가장 효율적이다.
1. OpenClaw 실행 여부
2. 토큰 정상 여부
3. 메시지 수신 로그 확인
4. chat_id 및 필터 확인
5. 명령어 조건 확인
6. 응답 전송 여부 확인
이 순서를 지키면 불필요하게 설정을 반복 수정하는 시간을 줄일 수 있다.
아쉬운 점이나 주의할 점
이 문제들은 대부분 OpenClaw 자체 문제라기보다 텔레그램 구조에서 오는 경우가 많다. 그래서 코드만 보고 해결하려 하면 계속 막힌다.
또 예시 코드는 방향을 보여주는 용도일 뿐, 그대로 붙여 넣으면 바로 동작하는 경우는 드물다. 환경마다 구조가 다르기 때문이다.
정리
OpenClaw Telegram 연동 오류는 복잡해 보이지만, 실제로는 몇 가지 패턴 안에서 반복된다. 중요한 건 문제를 많이 아는 것이 아니라, 어디부터 확인해야 하는지 아는 것이다.
특히 “메시지가 들어오는지 → 처리되는지 → 응답이 나가는지” 이 흐름만 기준으로 잡아도 대부분의 문제는 빠르게 해결할 수 있다.
이 기준이 잡히면 이후에는 같은 문제로 시간을 쓰는 일이 확실히 줄어든다.