통합10 분 소요

OpenClaw Telegram 통합 완전 가이드

Telegram 봇을 만들고 OpenClaw에 연결하는 방법을 알아보세요. 봇 생성, 구성, 명령, 그룹 채팅 설정을 다루는 전체 튜토리얼입니다.

OpenClaw Guides

Tutorial Authors

2025-02-04

개요

Telegram 통합을 사용하면 전용 Telegram 봇을 통해 OpenClaw와 상호 작용할 수 있습니다. OpenClaw는 기본적으로 grammY 프레임워크를 사용하여 롱 폴링을 수행하며, 프로덕션 배포를 위한 선택적 웹훅 지원도 제공합니다.

사전 요구 사항

OpenClaw 설치 및 실행 중
Telegram 계정

1단계: Telegram 봇 생성

BotFather와 대화

Telegram을 열고 @BotFather 검색
채팅을 시작하고 /newbot 전송
안내에 따르기:

You: /newbot

BotFather: Alright, a new bot. How are we going to call it?
           Please choose a name for your bot.

You: My OpenClaw Assistant

BotFather: Good. Now let's choose a username for your bot.
           It must end in `bot`. Like this, for example:
           TetrisBot or tetris_bot.

You: myopenclaw_bot

BotFather: Done! Congratulations on your new bot. You will find it at
           t.me/myopenclaw_bot. You can now add a description, about
           section and profile picture for your bot.

           Use this token to access the HTTP API:
           123456789:ABCdefGHIjklMNOpqrsTUVwxyz

           Keep your token secure and store it safely.

봇 토큰을 저장하세요 — 다음 단계에서 필요합니다.

개인정보 보호 모드 비활성화 (그룹 사용 시 권장)

그룹 채팅에서 봇을 사용할 계획이라면, 모든 메시지를 읽을 수 있도록 개인정보 보호 모드를 비활성화하세요:

/setprivacy
@myopenclaw_bot
Disable

개인정보 보호 모드를 변경한 후에는 변경 사항이 적용되도록 기존 그룹에서 봇을 제거한 다음 다시 추가해야 합니다. 또는 봇을 그룹 관리자로 승격시키세요 — 관리자 봇은 항상 모든 메시지를 수신합니다.

2단계: OpenClaw 구성

토큰 저장

봇 토큰을 두 가지 방법으로 저장할 수 있습니다. 설정 파일이 환경 변수보다 우선합니다.

옵션 A — 환경 변수:

bash

# ~/.openclaw/.env에 추가
TELEGRAM_BOT_TOKEN=123456789:ABCdefGHIjklMNOpqrsTUVwxyz

옵션 B — 설정에 직접 입력:

json5

// ~/.openclaw/openclaw.json
{
  channels: {
    telegram: {
      botToken: "123456789:ABCdefGHIjklMNOpqrsTUVwxyz"
    }
  }
}

최소 구성

~/.openclaw/openclaw.json 편집:

json5

{
  channels: {
    telegram: {
      // 환경 변수 TELEGRAM_BOT_TOKEN의 토큰 또는 botToken을 직접 설정
    }
  }
}

이것만으로 충분합니다 — Telegram 채널이 구성되면 OpenClaw가 자동으로 롱 폴링을 시작합니다.

3단계: 봇 테스트

Telegram을 열고 봇 사용자 이름 검색
/start로 채팅 시작
아무 메시지나 보내서 테스트

접근 제어 — DM 정책

dmPolicy를 통해 비공개 채팅에서 봇에게 메시지를 보낼 수 있는 사용자를 제어합니다:

| 정책 | 동작 | |------|------| | "pairing" (기본값) | 알 수 없는 발신자에게 만료되는 페어링 코드 발급; CLI에서 승인 | | "allowlist" | allowFrom의 사용자 ID / @사용자이름만 메시지 가능 | | "open" | 누구나 봇에게 메시지 가능 | | "disabled" | DM 완전 비활성화 |

페어링 모드 (기본값)

새 사용자가 봇에게 메시지를 보내면 페어링 코드를 받습니다. 다음 명령으로 승인하세요:

bash

# 대기 중인 페어링 요청 목록
openclaw pairing list telegram

# 특정 코드 승인
openclaw pairing approve telegram <CODE>

페어링 코드는 1시간 후 만료됩니다.

허용 목록 모드

json5

{
  channels: {
    telegram: {
      dmPolicy: "allowlist",
      allowFrom: [123456789, "@trusted_user"]
    }
  }
}

개방 모드

json5

{
  channels: {
    telegram: {
      dmPolicy: "open"
    }
  }
}

그룹 채팅 지원

그룹 접근 활성화

groups 객체에 그룹 ID를 추가합니다. "*"를 사용하면 모든 그룹을 허용합니다:

json5

{
  channels: {
    telegram: {
      groups: {
        "-1001234567890": {},           // 기본값을 사용하는 특정 그룹
        "-1009876543210": {             // 재정의가 있는 특정 그룹
          groupPolicy: "open",
          requireMention: false,
          systemPrompt: "You are a helpful coding assistant."
        }
      }
    }
  }
}

또는 모든 그룹 허용:

json5

{
  channels: {
    telegram: {
      groups: "*"
    }
  }
}

그룹 정책

그룹 내에서 봇과 상호 작용할 수 있는 사용자를 제어합니다:

| 설정 | 설명 | |------|------| | groupPolicy: "open" | 모든 그룹 멤버가 봇에게 메시지 가능 | | groupPolicy: "allowlist" | groupAllowFrom의 발신자만 상호 작용 가능 | | groupPolicy: "disabled" | 봇이 모든 그룹 메시지를 무시 |

json5

{
  channels: {
    telegram: {
      groupPolicy: "allowlist",
      groupAllowFrom: [123456789, "@allowed_user"]
    }
  }
}

멘션 요구 사항

기본적으로 봇은 그룹에서 @멘션이 필요합니다. 그룹별로 변경할 수 있습니다:

json5

{
  channels: {
    telegram: {
      groups: {
        "-1001234567890": {
          requireMention: false   // 봇이 모든 메시지에 응답
        }
      }
    }
  }
}

또는 그룹 채팅에서 세션 전용 명령 /activation always를 사용하세요.

그룹별 재정의

각 그룹 항목은 다음 필드를 지원합니다:

| 필드 | 설명 | |------|------| | groupPolicy | 전역 그룹 정책 재정의 | | requireMention | @멘션 필요 여부 | | skills | 이 그룹에서 사용 가능한 스킬 | | allowFrom | 이 그룹의 발신자 허용 목록 | | systemPrompt | 이 그룹의 사용자 정의 시스템 프롬프트 | | enabled | 이 특정 그룹의 활성화/비활성화 |

메시지 형식 및 청킹

HTML 파싱 모드

OpenClaw는 Telegram의 HTML 파싱 모드를 사용하여 메시지를 전송합니다 (Markdown이 아님). LLM의 Markdown은 자동으로 HTML 안전 태그로 변환됩니다. Telegram이 HTML을 거부하면 메시지는 일반 텍스트로 재시도됩니다.

텍스트 청킹

긴 메시지는 여러 Telegram 메시지로 분할됩니다:

json5

{
  channels: {
    telegram: {
      textChunkLimit: 4000,    // 메시지당 최대 문자 수 (기본값: 4000)
      chunkMode: "newline"     // "length" (기본값) 또는 "newline"
    }
  }
}

"length" — 문자 제한에서 분할
"newline" — 길이 제한을 적용하기 전에 단락 경계에서 분할

미디어 처리

미디어 크기 제한

json5

{
  channels: {
    telegram: {
      mediaMaxMb: 5    // 최대 파일 크기 (MB 단위, 기본값: 5)
    }
  }
}

스티커

정적 스티커 (WEBP)는 비전을 통해 처리되어 LLM에 설명됩니다
애니메이션/비디오 스티커는 건너뜁니다
스티커 설명은 중복 비전 호출을 방지하기 위해 ~/.openclaw/telegram/sticker-cache.json에 캐시됩니다

봇이 스티커를 전송할 수 있도록 설정하려면:

json5

{
  channels: {
    telegram: {
      actions: {
        sticker: true    // 기본값: false
      }
    }
  }
}

히스토리 및 컨텍스트

json5

{
  channels: {
    telegram: {
      historyLimit: 50,        // 그룹 컨텍스트 (기본값: 50)
      dmHistoryLimit: 100      // DM 컨텍스트
    }
  }
}

사용자별 DM 재정의:

json5

{
  channels: {
    telegram: {
      dms: {
        "123456789": {
          historyLimit: 200
        }
      }
    }
  }
}

히스토리를 비활성화하려면 0으로 설정하세요.

스트리밍

OpenClaw는 비공개 채팅에서 초안 기반 스트리밍을 지원합니다 (포럼 토픽 활성화 시):

| 설정 | 설명 | |------|------| | streamMode: "off" | 스트리밍 비활성화 (기본값) | | streamMode: "partial" | 초안 메시지에 연속 업데이트 | | streamMode: "block" | 초안 메시지에 청크 단위 업데이트 |

블록 모드 설정:

json5

{
  channels: {
    telegram: {
      streamMode: "block",
      draftChunk: {
        minChars: 200,
        maxChars: 800,
        breakPreference: "paragraph"
      }
    }
  }
}

웹훅 모드 (프로덕션)

프로덕션 배포에서는 롱 폴링 대신 웹훅을 사용하세요:

json5

{
  channels: {
    telegram: {
      webhookUrl: "https://your-domain.com/telegram-webhook",
      webhookSecret: "your-random-secret-string",
      webhookPath: "/telegram-webhook"    // 로컬 경로, 기본값: /telegram-webhook
    }
  }
}

웹훅 리스너는 0.0.0.0:8787에 바인딩됩니다. webhookUrl이 설정되면 OpenClaw는 자동으로 폴링에서 웹훅 모드로 전환합니다.

명령

기본 명령

OpenClaw는 시작 시 이러한 명령을 Telegram의 봇 메뉴에 등록합니다:

| 명령 | 설명 | |------|------| | /start | 환영 메시지 | | /status | 봇 상태 표시 | | /reset | 대화 초기화 | | /model | 모델 표시 / 전환 |

사용자 정의 명령

설정을 통해 메뉴 항목 추가 (메뉴 전용 — 다른 곳에서 처리하지 않으면 실행되지 않음):

json5

{
  channels: {
    telegram: {
      customCommands: [
        { command: "weather", description: "Get weather forecast" },
        { command: "translate", description: "Translate text" }
      ]
    }
  }
}

명령 이름은 소문자 a-z0-9_, 1~32자여야 합니다. 앞의 /는 자동으로 제거됩니다. 기본 명령은 재정의할 수 없습니다.

인라인 버튼

인라인 버튼 사용 가능 여부 제어:

| 설정 | 범위 | |------|------| | capabilities.inlineButtons: "off" | 비활성화 | | capabilities.inlineButtons: "dm" | DM 전용 | | capabilities.inlineButtons: "group" | 그룹 전용 | | capabilities.inlineButtons: "all" | DM 및 그룹 모두 | | capabilities.inlineButtons: "allowlist" | 모두 + 발신자 필터링 (기본값) |

네트워크 및 프록시

json5

{
  channels: {
    telegram: {
      timeoutSeconds: 500,        // Bot API 요청 타임아웃 (기본값: 500)
      network: {
        autoSelectFamily: false   // Happy Eyeballs 비활성화 (Node 22 기본값)
      },
      proxy: "socks5://127.0.0.1:1080"   // Bot API용 SOCKS/HTTP 프록시
    }
  }
}

문제 해결

봇이 응답하지 않음

토큰이 올바른지 확인:

bash

curl "https://api.telegram.org/bot<TOKEN>/getMe"

OpenClaw 로그 확인:

bash

openclaw logs --follow

그룹에서 메시지가 도착하지 않음

개인정보 보호 모드를 비활성화해야 합니다 (/setprivacy → Disable) 또는 봇이 관리자여야 합니다
/activation always (세션 전용)로 테스트하세요; 설정의 requireMention: false로 영구 적용

IPv6 라우팅 실패

IPv6 라우팅이 실패하면 봇이 조용히 응답을 중단할 수 있습니다. api.telegram.org의 DNS를 확인하세요:

bash

dig api.telegram.org AAAA

IPv6 이그레스를 활성화하거나 IPv4를 강제하여 해결:

bash

# /etc/hosts에 추가
149.154.167.220  api.telegram.org

또는 네트워크 설정 사용:

json5

{
  channels: {
    telegram: {
      network: {
        autoSelectFamily: false
      }
    }
  }
}

롱 폴링 중단 (Node 22+)

Node 22는 AbortSignal 인스턴스에 대해 더 엄격합니다. OpenClaw를 최신 버전으로 업그레이드하거나 Node 20으로 다운그레이드하세요.

`setMyCommands` 실패

api.telegram.org로의 아웃바운드 HTTPS/DNS가 차단되었을 수 있습니다. 방화벽 규칙을 확인하세요.

보안 모범 사례

봇 토큰을 절대 공유하지 마세요 — 유출된 경우 BotFather를 통해 즉시 취소하세요
DM 접근 제어에 페어링 또는 허용 목록을 사용하세요
그룹 내 상호 작용을 제어하기 위해 그룹 정책을 설정하세요
사용자 ID는 안전하게 확인하세요 — openclaw logs --follow 또는 Bot API의 getUpdates 엔드포인트를 사용하고, 서드파티 ID 봇은 피하세요
프로덕션 배포에는 시크릿이 포함된 웹훅을 사용하세요

개요

사전 요구 사항

1단계: Telegram 봇 생성

BotFather와 대화

개인정보 보호 모드 비활성화 (그룹 사용 시 권장)

2단계: OpenClaw 구성

토큰 저장

최소 구성

3단계: 봇 테스트

접근 제어 — DM 정책

페어링 모드 (기본값)

허용 목록 모드

개방 모드

그룹 채팅 지원

그룹 접근 활성화

그룹 정책

멘션 요구 사항

그룹별 재정의

메시지 형식 및 청킹

HTML 파싱 모드

텍스트 청킹

미디어 처리

미디어 크기 제한

스티커

히스토리 및 컨텍스트

스트리밍

웹훅 모드 (프로덕션)

명령

기본 명령

사용자 정의 명령

인라인 버튼

네트워크 및 프록시

문제 해결

봇이 응답하지 않음

그룹에서 메시지가 도착하지 않음

IPv6 라우팅 실패

롱 폴링 중단 (Node 22+)

setMyCommands 실패

보안 모범 사례

다음 단계

`setMyCommands` 실패