🦞 22. 텔레그램 그룹 협업 세팅 + 보안 가이드

OpenClaw를 텔레그램 그룹에 초대해 팀처럼 함께 일하려면, 서버 정책 적용 → BotFather 권한/프라이버시 설정 → 그룹 재초대/검증 순서로 세팅하는 게 가장 안전합니다. 이 문서는 실무에서 바로 쓰는 기준으로, 서버 쪽 변경과 텔레그램 쪽 설정을 한 번에 정리했습니다.

안내: 본문은 생성형 AI를 활용해 작성·정리했습니다.

flowchart LR
A[기존 봇 확인/토큰 준비] --> B[서버 설정 반영]
B --> C[hot reload 로그 확인]
C --> D[BotFather 권한/프라이버시 설정]
D --> E[그룹에서 봇 재초대]
E --> F[멘션/슬래시 테스트]
F --> G[보안 기본값으로 고정]

1) 시작 전에: 목표를 먼저 정하기

먼저 “이 그룹에서 OpenClaw가 어디까지 반응할지”를 정합니다.

• 권장 기본값(안전 우선)
  • 그룹에서 봇 호출 시에만 반응 (requireMention: true)
  • DM은 승인제 (dmPolicy: pairing)
  • 그룹 발화자는 제한 (groupPolicy: allowlist)
• 점검/복구 모드(잠시 완화)
  • 특정 그룹에서 멘션 없이 반응 (requireMention: false)
  • 특정 그룹에서 오픈 (groupPolicy: open)

핵심은 간단합니다. 점검할 때만 열고, 정상화되면 다시 좁히세요.

2) 15분 세팅: 서버 + BotFather + 그룹 검증

Step A. 새 봇 생성은 “필수 아님” (기존 봇 재사용 가능)

이미 운영 중인 봇이 있으면 그 봇을 그대로 그룹에 초대하면 됩니다. 굳이 새 봇을 만들 필요가 없습니다.

• 기존 봇 확인: @BotFather → /mybots → 봇 선택
• 토큰 재발급/확인: /token
• 새 봇은 정말 필요할 때만 /newbot

토큰은 비밀번호와 같습니다. 채팅방/문서/깃에 올리지 마세요.

Step B. 서버(OpenClaw) 설정 먼저 반영

1) 운영 기본 템플릿(권장, ID 개별등록 최소화)

{
  channels: {
    telegram: {
      enabled: true,
      botToken: "123:abc",
      dmPolicy: "pairing",
      groupPolicy: "allowlist", // 그룹 자체는 화이트리스트
      groups: {
        "-1001234567890": {
          requireMention: true,
          groupPolicy: "open" // 이 그룹 안에서는 사용자 ID 개별등록 없이 허용
        }
      }
    }
  }
}

• 이 템플릿은 허용한 그룹에서만 동작하면서, 그룹 내부 사용자 ID를 하나씩 넣지 않아도 됩니다.
• 사용자까지 제한하고 싶을 때만 groupAllowFrom을 추가하세요.

2) 점검용 오픈 템플릿(일시적)

{
  channels: {
    telegram: {
      enabled: true,
      botToken: "123:abc",
      groups: {
        "-1001234567890": {
          requireMention: false,
          groupPolicy: "open"
        }
      }
    }
  }
}

• 이 모드는 테스트/복구용으로만 잠깐 사용하고, 정상 동작 확인 후 권장 기본값으로 되돌리세요.

3) 반영 확인

openclaw gateway status
openclaw logs --follow

로그에서 아래와 같은 문구가 보이면 설정 반영 성공:

• config hot reload applied

필요 시 재시작:

openclaw gateway restart

Step C. BotFather에서 권한/프라이버시 설정

아래를 반드시 확인하세요.

1. /setprivacy → @OC0201bot → Disable
2. /setjoingroups → @OC0201bot → 그룹 참여 허용(Enable)
3. 텔레그램 그룹 내 봇 권한에서 메시지 보내기 허용

Step D. 그룹에서 봇 제거 후 재초대 (중요)

프라이버시 설정을 바꿨다면, 적용을 위해 아래를 권장합니다.

1. 그룹에서 봇 제거
2. 같은 봇을 다시 초대
3. 테스트 메시지 실행
   • @OC0201bot 테스트
   • /start@OC0201bot

Step E. DM 페어링 승인(권장)

openclaw pairing list telegram
openclaw pairing approve telegram <CODE>

• pairing 모드에서는 승인 전 DM은 처리되지 않습니다.
• 코드 유효시간은 1시간입니다.

3) 운영 모드 2가지 + mentionPatterns 차이 (실무 핵심)

모드 1) 멘션 호출형 (권장)

• 원칙: 봇을 “호출”했을 때만 반응
• 기본 트리거: 텔레그램 네이티브 멘션(@봇이름)
• 확장 트리거: mentionPatterns에 등록한 호출어
• 장점: 소음 적고, 오작동 위험 낮음
• 설정: requireMention: true

모드 2) 상시 반응형 (주의)

• 그룹 대화 대부분에 반응 가능
• 장점: 자동화 밀도 높음
• 리스크: 불필요 응답, 권한 오남용 가능성 증가
• 설정: requireMention: false + 강한 운영 통제 필수

@멘션 vs mentionPatterns 차이

구분	트리거 방식	장점	주의점	추천 상황
@봇이름	텔레그램 네이티브 멘션	가장 명확, 오작동 적음	사용자가 매번 @를 써야 함	기본 운영(권장)
mentionPatterns	지정한 키워드/문구(예: openclaw, 오씨)도 멘션으로 인식	@ 없이도 호출 가능해 UX 좋음	패턴을 넓게 잡으면 오탐 가능	익숙한 팀 협업 환경

즉, mentionPatterns는 “@를 완전히 없애는 기능”이라기보다, requireMention:true를 유지한 채 호출 방법을 넓히는 장치입니다.

예시 설정 (@ 없이도 지정 키워드로 호출)

{
  messages: {
    groupChat: {
      mentionPatterns: ["@?oc0201bot", "@?openclaw", "오씨", "플럭스"]
    }
  },
  channels: {
    telegram: {
      groups: {
        "-1001234567890": {
          requireMention: true,
          groupPolicy: "open"
        }
      }
    }
  }
}

groupPolicy: allowlist일 때 권한을 어디까지 잠글지 (덜 헷갈리게)

allowlist는 사실 2단계입니다.

1. 그룹 화이트리스트: channels.telegram.groups
   • 어떤 그룹을 허용할지 정함
2. 그룹 내부 사용자 화이트리스트(선택): channels.telegram.groupAllowFrom
   • 허용된 그룹 안에서도 특정 사람만 트리거하게 제한

처음에는 보통 아래처럼 시작하면 가장 덜 복잡합니다.

• 루트: groupPolicy: "allowlist"
• 그룹별: groups.<chatId>.groupPolicy: "open"
• 트리거: requireMention: true (+ 필요 시 mentionPatterns)

이렇게 하면 허용한 그룹 안에서는 사용자 ID를 하나씩 넣을 필요가 없습니다.

정말 보안이 필요한 그룹에서만 groupAllowFrom을 추가해 “특정 사용자만”으로 좁히세요.

3단계 권한 프리셋

• 프리셋 A (권장 시작점)
  • 그룹만 제한: groupPolicy=allowlist, groups.<id>.groupPolicy=open, requireMention=true
• 프리셋 B (중간 보안)
  • A + mentionPatterns 최소 등록(팀 호출어 2~4개)
• 프리셋 C (강보안)
  • A 또는 B + groupAllowFrom=["<userId>", ...]

4) 보안 주의사항 (꼭 지킬 10개)

1. 토큰을 코드/깃에 커밋하지 않기
   • 가능하면 tokenFile 또는 환경변수 사용
2. DM은 pairing 또는 allowlist로 제한
   • dmPolicy: open은 특별한 이유 없으면 금지
3. 그룹은 allowlist부터 시작
   • groupPolicy: open은 특정 그룹에만 제한 적용
4. 초기엔 멘션 필수 유지
   • requireMention: true로 잡음/오작동 방지
5. 텔레그램 Privacy Mode 변경 시 재초대 필수
   • /setprivacy 변경만으로 끝내지 말고 제거→재초대
6. 강한 도구는 기본 차단
   • gateway, cron, sessions_spawn, sessions_send 등은 신중히 열기
7. 정기 보안 진단 실행
   • openclaw security audit
   • openclaw security audit --deep
8. 권한 파일 접근권한 점검
   • ~/.openclaw 디렉토리 퍼미션 정기 확인
9. 그룹별 정책 분리
   • 모든 그룹에 동일 정책을 쓰지 말고, 그룹 성격별로 분리
10. 사고 시 즉시 차단 루틴 마련

• 토큰 재발급, 그룹 접근 제한, 페어링 재검토 순으로 대응

flowchart TD
A[새 그룹 추가 요청] --> B{신뢰 가능한 그룹인가?}
B -- 아니오 --> C[추가 보류]
B -- 예 --> D{기본정책 유지 가능?}
D -- 예 --> E[requireMention=true + allowlist]
D -- 아니오 --> F[예외정책 문서화]
F --> G[주간 재검토]
E --> G

5) 자주 막히는 문제 빠른 해결

서버 설정은 반영됐는데 무응답

• 로그에 config hot reload applied가 보이면 서버 반영은 된 상태
• 이 경우 남은 원인은 대부분 텔레그램 측 설정:
  • /setprivacy Disable
  • 그룹 권한(메시지 보내기)
  • 봇 제거 후 재초대
  • @봇 테스트, /start@봇 재검증

봇이 그룹에서 멘션 없이 반응 안 함

• requireMention 설정 확인
• groupPolicy가 open인지(점검 모드 기준) 확인
• Privacy Mode(/setprivacy) 변경 + 재초대 적용 여부 확인

그룹 메시지를 아예 못 읽음

• channels.telegram.groups에 해당 그룹 ID가 있는지 확인
• openclaw logs --follow로 skip reason 확인

명령이 일부만 동작

• sender가 allowlist/pairing 승인 상태인지 확인
• DNS/HTTPS 문제 시 setMyCommands failed 로그 확인

6) 운영 체크리스트 (복붙용)

• 기존 봇 재사용 여부 결정 (/mybots 확인)
• 서버 설정 반영 완료 (groupPolicy, requireMention, groups.<chatId>, 필요 시 groupAllowFrom)
• 로그에서 config hot reload applied 확인
• BotFather /setprivacy Disable 적용
• BotFather /setjoingroups 허용 확인
• 그룹에서 봇 메시지 권한 허용 확인
• 봇 제거 후 재초대 완료
• @봇 테스트, /start@봇 동작 확인
• mentionPatterns 사용 시 오탐 없는 호출어(팀 내 별칭)로 최소 패턴만 등록
• DM pairing 승인 흐름 테스트 완료
• 보안 감사 1회 실행 (security audit)

7) 실무 치트시트 (명령어)

# 채널 연결/상태
openclaw channels add --channel telegram --token <TOKEN>
openclaw gateway status
openclaw gateway restart
 
# 페어링 승인
openclaw pairing list telegram
openclaw pairing approve telegram <CODE>
 
# 로그 추적(반영/스킵 사유 확인)
openclaw logs --follow
 
# 보안 점검
openclaw security audit
openclaw security audit --deep

관련 문서

• OpenClaw 18: 텔레그램 안될 때 5분 복구
• OpenClaw 20: 운영 아키텍처·규칙 총정리
• OpenClaw 인덱스