🦞 30. OpenClaw 텔레그램 완전설정 운영가이드

OpenClaw를 텔레그램에 처음 붙이면 보통 같은 지점에서 막힌다. 봇은 살아 있는데 그룹에서 반응이 없고, 토픽마다 동작이 달라 보이고, 권한을 열면 편해지지만 운영 리스크가 갑자기 커진다.
이 문서는 그 시행착오를 줄이기 위해 BotFather 설정 → OpenClaw 연결 → 그룹/토픽 권한 분리 → 최종 검증 순서로 정리했다. 그대로 따라 하면 초반에 가장 많이 터지는 권한/반응 이슈를 빠르게 안정화할 수 있다.

flowchart LR
A[BotFather 생성/권한] --> B[OpenClaw 토큰 연결]
B --> C[DM 정책 설정]
C --> D[그룹 정책 설정]
D --> E[토픽 정책 분리]
E --> F[로그/보안점검]
F --> G[운영 배포]

먼저 이렇게 시작하면 안전하다

가장 사고가 적은 시작값은 **DM은 pairing, 그룹은 allowlist, 기본은 멘션 필수(requireMention=true)**다. 운영 중 필요한 토픽만 예외로 열면, 편의성과 안정성을 동시에 확보하기 쉽다.

1) BotFather에서 먼저 끝내야 하는 설정

OpenClaw 이전에 텔레그램 봇의 수신 범위를 먼저 잡아야 한다.

1-1. 봇 생성

1. 텔레그램에서 @BotFather 접속
2. /newbot
3. 이름/username 지정
4. 토큰 발급 후 안전하게 보관

1-2. 그룹 운영용 핵심 토글

• /setjoingroups : 그룹 추가 허용 여부
• /setprivacy : Privacy Mode

Privacy Mode 운영 기준:

• ON(기본): 멘션/명령 중심으로만 수신 (안전)
• OFF: 그룹 메시지를 광범위 수신 (편하지만 잡음/오작동 위험 증가)

Privacy Mode를 바꿨다면, 그룹에서 봇을 제거 후 재초대해야 반영이 깔끔하다.

2) OpenClaw 텔레그램 기본 연결

토큰을 붙이고 가장 안전한 기본값으로 시작한다.

{
  channels: {
    telegram: {
      enabled: true,
      botToken: "123456:ABC...",
      dmPolicy: "pairing",
      groupPolicy: "allowlist",
      groups: {
        "*": { requireMention: true }
      }
    }
  }
}

반영:

openclaw gateway restart
openclaw status --deep

3) DM(1:1) 권한 설정 — 누구를 받을지

권장: pairing

처음 메시지는 페어링 코드로 대기시키고, 승인된 사용자만 처리한다.

openclaw pairing list telegram
openclaw pairing approve telegram <CODE>

다른 선택지

• allowlist: 특정 사용자 ID만 허용
• open: 누구나 허용(운영용 비권장)
• disabled: DM 비활성

3-1) DM 좌상단 new chat +는 누가 만드는가 (중요)

많이 헷갈리는 지점인데, DM 좌상단 new chat +는 BotFather 권한으로 켜는 기능이 아니다. OpenClaw가 버튼을 생성하는 것도 아니다. 이 버튼은 텔레그램 클라이언트가 제공하는 UI다.

운영 관점에서 중요한 건 버튼 자체보다 message_thread_id가 들어오느냐다.

• message_thread_id가 있는 DM 메시지: OpenClaw가 thread-aware 세션으로 분리해 관리
• message_thread_id가 없는 일반 DM 메시지: 기존 DM 세션 규칙(dmScope)으로 처리

즉, 주제별 새 대화가 자동 분리되는 구조를 만들고 싶다면 권한 토글보다 다음 2가지를 맞추면 된다.

1. OpenClaw에서 thread 처리 활성화(session.threadBindings.enabled=true)
2. 다른 봇/백엔드에서도 답장 시 동일 message_thread_id를 유지

검증은 openclaw logs --follow에서 message_thread_id 유입 여부를 먼저 확인하는 게 가장 빠르다.

4) 그룹 권한 설정 — 사고를 줄이는 핵심 포인트

그룹은 아래 4가지를 함께 봐야 한다.

1. groups : 허용할 그룹 목록
2. groupPolicy : 그룹 발화자 정책 (allowlist | open | disabled)
3. groupAllowFrom : 그룹에서 말 걸 수 있는 사용자 제한
4. requireMention : 멘션해야 반응할지

실무 기본 템플릿 (편의+안정 균형)

{
  channels: {
    telegram: {
      dmPolicy: "pairing",
      allowFrom: ["YOUR_TELEGRAM_USER_ID"],
 
      groupPolicy: "allowlist",
      groupAllowFrom: ["YOUR_TELEGRAM_USER_ID"],
 
      groups: {
        "*": { requireMention: true },
        "-1001234567890": {
          groupPolicy: "allowlist",
          requireMention: true
        }
      }
    }
  }
}

5) 그룹 주제(Forum Topic) 설정 — 토픽별 분리 운영

포럼형 그룹에서는 토픽별로 정책을 나눌 수 있다.

{
  channels: {
    telegram: {
      groups: {
        "-1001234567890": {
          requireMention: true,
          topics: {
            "1": { requireMention: true },
            "12": {
              requireMention: false,
              groupPolicy: "allowlist",
              allowFrom: ["YOUR_TELEGRAM_USER_ID"],
              agentId: "main"
            },
            "34": {
              requireMention: true,
              agentId: "youtube-analyzer"
            }
          }
        }
      }
    }
  }
}

토픽 ID 확인은 보통 openclaw logs --follow에서 message_thread_id로 잡는다.

6) 텔레그램 그룹 권한(관리자 권한) 체크

OpenClaw 설정이 맞아도, 텔레그램 그룹 권한이 부족하면 동작이 제한된다.

• 일반 답변: 멤버 권한으로도 충분한 경우 많음
• 그룹 전체 메시지 인식: Privacy Mode OFF 또는 관리자 권한 필요 가능
• 토픽 생성/관리 자동화: 토픽 관리 권한 필요
• 메시지 삭제/수정 자동화: 해당 관리 권한 필요

🧠 칠판 치트시트

1. BotFather: /newbot, /setjoingroups, /setprivacy
2. OpenClaw: botToken + dmPolicy + groupPolicy부터 고정
3. 그룹 기본은 allowlist + requireMention=true
4. 토픽은 groups.<chatId>.topics.<threadId>로 분리
5. 마지막은 security audit --deep로 검증

7) 20분 도입 루틴

0~5분: 봇 생성 + BotFather 토글

• /newbot
• /setjoingroups
• /setprivacy

5~10분: OpenClaw 연결

• botToken 입력
• dmPolicy, groupPolicy, groups.*.requireMention 설정

10~15분: 그룹/토픽 검증

• DM 1건
• 그룹 멘션 1건
• 토픽 1건

15~20분: 운영 점검

openclaw status --deep
openclaw logs --follow
openclaw security audit --deep

8) 자주 막히는 문제와 즉시 확인 포인트

증상 A: DM은 되는데 그룹이 침묵

• groups에 해당 chat ID가 있는지
• requireMention이 true인데 실제 멘션했는지
• BotFather privacy 상태가 의도와 맞는지

증상 B: 특정 토픽에서만 반응 안 함

• topics.<threadId> 숫자 일치 확인
• 해당 토픽에 allowFrom/groupPolicy 예외가 걸려 있는지

증상 C: 예전엔 되던 호출이 막힘

• groupPolicy=open에서 allowlist로 바뀌었는지
• groupAllowFrom 미설정으로 차단되는지
• 보안 점검 결과에서 critical/warn 항목 재확인

증상 D: 버튼은 보이는데 콜백(callback)이 안 올라옴

버튼 콜백 이슈는 대부분 봇 고장보다 경로/정책/권한 불일치로 생긴다. 아래 순서대로 보면 10분 안에 원인을 좁힐 수 있다.

1. 채널 상태부터 확인

openclaw channels status --probe

• running, works, audit ok가 아니면 gateway 상태부터 복구한다.

2. 그룹에서만 실패하면 BotFather privacy mode 확인

• /setprivacy에서 운영 의도와 일치하는지 점검
• 변경 후 gateway 재시작

openclaw gateway restart
openclaw channels status --probe

3. 기능 경로 실측 테스트

• 전송(send)
• 수정(edit)
• 반응(react)
• 삭제(delete)
• 버튼 전송 후 callback 수신

이 5개가 연속 통과하면 라우팅은 정상이고, 이후 문제는 특정 그룹/토픽 정책으로 좁혀서 잡을 수 있다.

버튼 콜백 10분 복구 체크리스트

• openclaw channels status --probe 확인
• running/works/audit ok 상태 확인
• BotFather privacy mode 확인
• gateway 재시작 후 재검증
• callback 테스트 3회 연속 통과

9) 운영용 권한 프로필 3단계

프로필	핵심 설정	추천 상황
보수형	pairing + allowlist + requireMention=true	운영방/업무방
균형형	보수형 + 일부 토픽 requireMention=false	팀 협업 실사용
개방형	groupPolicy=open, 멘션 완화	테스트/임시 이벤트

개방형은 편하지만, 장기 운영 기본값으로 두지 않는 것을 권장한다.

10) 최종 점검 체크리스트

• BotFather 토큰 정상
• /setjoingroups, /setprivacy 확인
• channels.telegram.botToken 반영
• DM 정책(pairing/allowlist) 확인
• DM thread(message_thread_id) 유입/답장 유지 확인
• 그룹 정책(groupPolicy, groupAllowFrom) 확인
• 토픽 정책(topics.threadId) 확인
• openclaw status --deep 정상
• openclaw security audit --deep critical 0 목표

다음 읽기

• 11. 연동체크
• 12. 브라우저 릴레이 연동 구조
• 15. 캐싱 완전 가이드
• 18. 텔레그램 5분 복구
• 20. 운영아키텍처 규칙 총정리
• 22. 그룹 협업 세팅 + 보안
• 23. plaintext ws 보안에러 해결
• 25. 크론 서브에이전트 분산운영
• 28. 듀얼 릴레이 운영 가이드
• 29. 텔레그램 권한변화 버전비교

AI 생성 고지: 이 문서는 OpenClaw/Telegram 공식 문서를 바탕으로 생성형 AI를 활용해 작성·편집되었습니다.