Telegram은 OpenClaw이 네이티브로 지원하는 채널 중 하나이며, 하위 계층에서 grammY 프레임워크를 사용합니다. Telegram의 그룹 및 채널 기능은 매우 강력하며, 네이티브 Bot API, 세밀한 권한 제어 및 풍부한 메시지 형식을 보유하고 있습니다. 이 글에서는 OpenClaw의 Telegram 그룹 시나리오에서의 고급 설정 옵션을 심층적으로 소개합니다.
Telegram 그룹 유형
Telegram에는 여러 종류의 그룹 유형이 있으며, 그 차이를 이해하면 Bot을 적절하게 설정하는 데 도움이 됩니다:
일반 그룹: 최대 200명의 소규모 그룹입니다. Bot은 모든 메시지를 수신하거나(Privacy Mode를 끈 경우) 명령과 @멘션 메시지만 수신할 수 있습니다.
슈퍼 그룹(Supergroup): 최대 200,000명의 대규모 그룹으로, 더 많은 관리 기능을 지원합니다. 대부분의 커뮤니티에서 사용하는 그룹 유형입니다.
채널(Channel): 단방향 브로드캐스트 채널입니다. Bot은 관리자로서 메시지를 게시할 수 있지만, 인터랙티브 AI 대화에는 보통 사용되지 않습니다.
Privacy Mode와 메시지 수신
Telegram Bot은 기본적으로 Privacy Mode가 활성화되어 있어, 그룹에서 Bot은 다음 메시지만 수신할 수 있습니다: /로 시작하는 명령, Bot을 직접 @멘션한 메시지, Bot이 보낸 메시지에 대한 답장, 그리고 서비스 메시지(멤버 입퇴장 등).
Bot이 그룹의 모든 메시지를 수신하도록 하려면 BotFather에서 Privacy Mode를 꺼야 합니다. /setprivacy 명령을 보내고 Bot을 선택한 후 Disabled로 설정합니다. 수정 후에는 Bot을 그룹에서 제거했다가 다시 추가해야 적용됩니다.
openclaw.json에서 그룹 동작을 설정합니다:
{
"channels": {
"telegram": {
"enabled": true,
"token": "your-bot-token",
"groups": {
"privacyMode": false,
"triggerMode": "command_and_mention",
"commands": ["/ask", "/chat", "/help"]
}
}
}
}
명령 시스템
Telegram의 명령 시스템은 Bot과 상호작용하는 표준 방식입니다. OpenClaw에서는 여러 명령을 정의할 수 있으며, 각 명령에 다른 동작을 바인딩할 수 있습니다:
{
"channels": {
"telegram": {
"groups": {
"commands": {
"/ask": {
"description": "AI에게 질문하기",
"behavior": "single_response"
},
"/chat": {
"description": "다중 턴 대화 시작",
"behavior": "conversation"
},
"/reset": {
"description": "대화 컨텍스트 초기화",
"behavior": "reset_context"
}
}
}
}
}
}
single_response 모드에서 Bot은 한 번만 응답하고, conversation 모드에서 Bot은 해당 사용자의 후속 메시지를 지속적으로 추적합니다(타임아웃 또는 수동 초기화까지). BotFather에서 /setcommands로 이 명령들을 등록하면, 사용자가 /를 입력할 때 명령 목록과 설명을 볼 수 있습니다.
그룹 권한 제어
OpenClaw은 다층적 Telegram 그룹 권한 제어를 제공합니다:
{
"channels": {
"telegram": {
"groups": {
"allowedGroups": [-1001234567890, -1009876543210],
"userAllowlist": [123456789, 987654321],
"adminOnly": false,
"requirePairing": false
}
}
}
}
그룹 화이트리스트(allowedGroups): Telegram 그룹의 chat_id를 사용하여 Bot이 특정 그룹에서만 작동하도록 제한합니다. Chat ID는 음수이며, Bot이 그룹 메시지를 수신하도록 하여 얻을 수 있습니다.
사용자 화이트리스트(userAllowlist): 특정 사용자 ID만 그룹에서 AI를 트리거할 수 있도록 제한합니다. 다른 사용자의 메시지는 무시됩니다.
관리자만(adminOnly): true로 설정하면, 그룹 관리자만 AI 기능을 사용할 수 있습니다.
DM 페어링(requirePairing): 사용자가 먼저 개인 채팅으로 Bot과 페어링 인증을 완료해야 합니다.
이러한 옵션은 조합하여 사용할 수 있습니다. 예를 들어, 특정 그룹에서 페어링된 사용자만 Bot을 사용할 수 있도록 설정할 수 있습니다.
인라인 모드
Telegram Bot은 인라인 모드(Inline Mode)를 지원하며, 사용자는 어떤 채팅에서든 @botname 질문 방식으로 AI를 호출할 수 있습니다. Bot을 그룹에 추가할 필요가 없습니다. BotFather에서 인라인 모드를 활성화한 후, OpenClaw에서 설정합니다:
{
"channels": {
"telegram": {
"inlineMode": {
"enabled": true,
"cacheTime": 30
}
}
}
}
인라인 모드의 답변은 인라인 쿼리 결과 형태로 표시되며, 사용자가 선택하면 결과가 현재 대화에 전송됩니다.
다중 봇 관리
대규모 커뮤니티에서는 각각 다른 역할을 담당하는 여러 AI Bot을 배포해야 할 수 있습니다. OpenClaw은 하나의 인스턴스에서 여러 Telegram Bot을 실행하는 것을 지원합니다:
{
"channels": {
"telegram": [
{
"name": "general-assistant",
"token": "bot-token-1",
"model": "gpt-4"
},
{
"name": "code-helper",
"token": "bot-token-2",
"model": "claude-sonnet"
}
]
}
}
각 Bot은 서로 다른 token과 모델 설정을 사용하며, 같은 그룹에서 공존할 수 있습니다. 사용자는 다른 Bot을 @하여 다른 AI 어시스턴트를 호출합니다.
메시지 형식과 Markdown
Telegram은 MarkdownV2와 HTML 두 가지 메시지 형식을 지원합니다. OpenClaw은 기본적으로 MarkdownV2를 사용하여 AI 응답을 포매팅하며, 볼드, 이탤릭, 코드 블록, 링크 등을 지원합니다. AI 응답에 복잡한 형식이 포함된 경우, OpenClaw은 Telegram이 올바르게 렌더링할 수 있도록 이스케이프 문자를 자동으로 처리합니다.
설정에서 HTML 형식이나 일반 텍스트로 전환할 수 있습니다:
{
"channels": {
"telegram": {
"parseMode": "MarkdownV2"
}
}
}
속도 제한 및 큐
Telegram Bot API에는 속도 제한이 있습니다: 초당 최대 30개 메시지, 같은 그룹에서 분당 최대 20개 메시지. OpenClaw에는 이러한 제한을 처리하는 내장 메시지 큐 메커니즘이 있습니다. 트래픽이 많은 그룹에서는 응답이 약간 지연될 수 있으며, 이는 정상적인 현상입니다.
문제 해결
Bot이 그룹에서 응답하지 않는 경우 다음 단계로 문제를 해결합니다: Bot이 그룹에 추가되었는지 확인하고, Privacy Mode 설정이 트리거 모드와 일치하는지 확인하고, 그룹 ID가 화이트리스트에 있는지 확인하고(화이트리스트를 설정한 경우), OpenClaw 로그에 오류 메시지가 있는지 확인합니다. openclaw channels status 명령으로 모든 채널의 연결 상태를 빠르게 확인할 수 있습니다.