OpenClaw를 Telegram과 연결할 때 많은 분이 가장 헷갈리는 구간이 바로 이 단계입니다. BotFather에서 토큰까지는 받아왔는데, 정작 OpenClaw 쪽 설정에서 어떤 키를 어디에 넣어야 하는지, 예전 문서처럼 명령어로 로그인하는 건지, 아니면 JSON 설정 파일을 직접 만져야 하는지 흐름이 한 번에 잡히지 않는 경우가 많습니다.
특히 최근 OpenClaw 문서를 보면 Telegram 채널은 예전 방식처럼 openclaw channels login telegram으로 붙이는 구조가 아니라, 설정 파일 또는 환경 변수에 bot token을 넣고 gateway를 실행하는 방식으로 안내됩니다. 공식 Telegram 채널 문서에도 Telegram은 config 또는 env로 토큰을 넣은 뒤 Gateway를 시작하라고 되어 있고, DM 기본 정책은 pairing으로 잡혀 있습니다.
이번 글에서는 OpenClaw 채널 설정에 Telegram을 추가하는 방법을, 실제로 따라 하기 쉬운 코드 중심으로 정리해보겠습니다. 단순히 “이렇게 넣으세요”에서 끝내지 않고, 초보자가 중간에 막히는 부분과 자주 헷갈리는 포인트도 함께 짚겠습니다.
먼저 알아둘 점
OpenClaw 공식 문서 기준으로 Telegram 채널의 기본 골격은 꽤 단순합니다. 핵심은 channels.telegram.enabled를 켜고, botToken을 넣고, DM 접근 정책을 정하는 것입니다. 가장 기본 예시는 아래와 비슷한 형태로 제시됩니다. 기본 DM 정책은 pairing이고, 그룹에서는 requireMention: true 같은 제한을 두는 예시가 같이 나옵니다.
{
"channels": {
"telegram": {
"enabled": true,
"botToken": "123:abc",
"dmPolicy": "pairing",
"groups": {
"*": {
"requireMention": true
}
}
}
}
}여기서 중요한 점은 두 가지입니다. 첫째, Telegram은 토큰 기반이라서 WhatsApp처럼 별도 로그인 절차를 거치는 채널과 느낌이 다릅니다. 둘째, 모르는 사용자가 DM을 보냈을 때 바로 열어두는 방식이 아니라, 기본적으로는 pairing 승인을 거치게 되어 있어 보안 면에서는 오히려 관리가 쉬운 편입니다. 공식 문서도 Telegram의 기본 DM 정책을 pairing으로 설명하고 있고, 승인 코드는 1시간 동안 유효하다고 안내합니다.
가장 먼저 할 일: 설정 파일 위치 확인
보통 OpenClaw를 기본 경로로 쓴다면 설정 파일은 사용자 홈 디렉터리 아래의 ~/.openclaw/openclaw.json 형태로 관리되는 경우가 많습니다. GitHub 이슈 예시에서도 실제 업데이트 대상 파일이 이 경로로 표시됩니다.
터미널에서 먼저 파일이 있는지 확인해봅니다.
ls ~/.openclaw
cat ~/.openclaw/openclaw.json파일이 없거나 내용이 비어 있다면, 아래처럼 최소 구성부터 직접 만들어도 됩니다.
mkdir -p ~/.openclaw
nano ~/.openclaw/openclaw.json실제로 넣으면 되는 Telegram 설정 코드
가장 무난하게 시작하는 방법은 아래 예시처럼 Telegram 채널만 우선 켜두는 것입니다. 이 코드는 개인 DM 위주로 먼저 테스트할 때 적합합니다.
{
"channels": {
"telegram": {
"enabled": true,
"botToken": "여기에_BotFather_토큰_입력",
"dmPolicy": "pairing"
}
}
}이 정도만 넣어도 Telegram DM 연동의 기본 뼈대는 잡힙니다. 다만 실제로 써보면 대부분은 “그룹에서도 쓰고 싶은데요?” 또는 “봇이 그룹에서 아무 반응이 없어요”에서 막힙니다. 그래서 처음부터 아래처럼 그룹 설정까지 같이 넣어두는 편이 더 실용적입니다.
{
"channels": {
"telegram": {
"enabled": true,
"botToken": "123456789:AAEXAMPLE_REPLACE_THIS",
"dmPolicy": "pairing",
"groups": {
"*": {
"requireMention": true
}
}
}
}
}이 설정의 의미는 비교적 단순합니다. Telegram 채널을 켜고, BotFather에서 받은 토큰을 사용하며, DM은 pairing 승인 방식으로 받고, 그룹에서는 아무 말에나 반응하지 않고 봇을 멘션했을 때만 응답하도록 제한하는 형태입니다. 공식 예시도 거의 같은 방향으로 안내합니다.
환경 변수 방식으로 넣고 싶다면
OpenClaw 문서에는 TELEGRAM_BOT_TOKEN 환경 변수 fallback도 안내되어 있습니다. 다만 이 값은 기본 account에 대한 fallback으로 쓰이는 구조라서, 단일 계정으로 간단히 시작할 때는 편하지만 나중에 계정을 여러 개 쓰게 되면 설정 파일에 명시적으로 적는 편이 더 덜 헷갈립니다. 구성 참조 문서도 bot token은 channels.telegram.botToken 또는 tokenFile을 우선 사용하고, 환경 변수는 default account fallback이라고 설명합니다.
환경 변수 방식 예시는 아래처럼 쓸 수 있습니다.
export TELEGRAM_BOT_TOKEN="123456789:AAEXAMPLE_REPLACE_THIS"
openclaw gateway영구 적용하려면 셸 설정 파일에 추가합니다.
echo 'export TELEGRAM_BOT_TOKEN="123456789:AAEXAMPLE_REPLACE_THIS"' >> ~/.bashrc
source ~/.bashrc다만 개인적으로는 블로그 독자분들 기준으로 처음 한 번은 JSON에 직접 넣어보는 방식이 더 이해하기 쉽다고 봅니다. 나중에 왜 안 되는지 확인할 때도 설정 위치가 한눈에 보이기 때문입니다.
설정 후 실행: 실제 명령어 순서
Telegram 토큰을 넣었다면 다음 단계는 Gateway 실행입니다. 공식 Telegram 문서에서는 아래 순서로 안내합니다. Gateway를 실행하고, pairing 목록을 확인한 뒤, 승인 코드를 approve 하는 흐름입니다.
openclaw gateway
openclaw pairing list telegram
openclaw pairing approve telegram <CODE>직접 따라 하기 쉽게 조금 더 풀어 쓰면 보통 이런 순서가 됩니다.
# 1) OpenClaw 게이트웨이 실행
openclaw gateway
# 2) Telegram에서 내 봇에게 아무 메시지나 하나 보냄
# 예: hi
# 3) 다른 터미널에서 pairing 요청 확인
openclaw pairing list telegram
# 4) 표시된 코드 승인
openclaw pairing approve telegram ABC123처음 DM을 보내면 바로 대화가 되는 것이 아니라 pairing 절차가 나오는 이유가 바로 이 정책 때문입니다. 공식 문서 기준으로 pending 요청과 allowlist는 ~/.openclaw/credentials/ 아래에 저장되며, 이것들은 사실상 접근 권한을 좌우하므로 민감 정보처럼 다루는 것이 좋습니다.
직접 써보면 가장 많이 헷갈리는 부분
여기서 가장 흔한 혼동은 예전 안내처럼 openclaw channels login telegram을 실행하는 경우입니다. 그런데 최근 이슈를 보면 이 명령은 현재 Telegram 설정 흐름과 맞지 않아 “too many arguments” 오류를 내는 사례가 실제로 보고됐습니다. 지금 기준으로는 Telegram 채널을 로그인 명령으로 붙이는 방식보다, config 또는 env에 토큰을 넣는 방식으로 생각하는 편이 맞습니다.
# 이렇게 하지 않는 편이 좋습니다
openclaw channels login telegram또 하나는 그룹에서 봇이 아무 반응이 없다고 느끼는 경우입니다. Telegram 자체의 Privacy Mode 때문에 그룹 메시지를 충분히 보지 못할 수 있는데, 공식 문서에서는 이 경우 /setprivacy로 privacy mode를 끄거나 봇을 그룹 관리자로 올리는 방법을 안내합니다. 그리고 privacy 설정을 바꾼 뒤에는 그룹에서 봇을 제거했다가 다시 추가해야 변경이 반영될 수 있다고 설명합니다.
그룹까지 제대로 쓰고 싶다면 이 코드가 더 현실적이다
개인적으로는 처음부터 아래 정도 구성을 추천합니다. 이유는 두 가지입니다. 하나는 멘션 기반이라 그룹에서 너무 시끄럽지 않고, 다른 하나는 나중에 DM과 그룹을 같이 테스트할 때 행동이 예측 가능하기 때문입니다.
{
"channels": {
"telegram": {
"enabled": true,
"botToken": "123456789:AAEXAMPLE_REPLACE_THIS",
"dmPolicy": "pairing",
"groups": {
"*": {
"requireMention": true
}
}
}
}
}여기서 그룹 기능이 필요한데도 봇이 조용하다면 아래 순서로 같이 점검하면 됩니다.
# 점검 체크
1. BotFather에서 받은 토큰이 맞는지
2. openclaw gateway가 실제로 실행 중인지
3. 그룹에 봇을 추가했는지
4. requireMention=true 라면 @봇이름 으로 멘션했는지
5. Telegram Privacy Mode를 조정했는지
6. Privacy Mode를 바꾼 뒤 그룹에서 봇을 재추가했는지플러그인 관련 이슈가 보인다면
최근 GitHub 이슈를 보면 일부 버전이나 설치 환경에서는 온보딩 화면에서 “telegram plugin not available” 메시지가 뜨는 사례도 있었습니다. 실제 이슈에서는 openclaw plugins enable telegram로 활성화해도 온보딩 화면이 계속 같은 메시지를 보여주는 경우가 보고됐습니다.
이 부분은 초보자 입장에서는 꽤 헷갈릴 수 있습니다. 다만 공식 문서 기준으로 Telegram 채널 자체는 production-ready로 안내되고 있어서, 문제가 생긴다면 “Telegram 기능이 원래 없는가?”보다는 설치 방식이나 버전, 플러그인 로더 상태, 재시작 여부를 먼저 의심하는 편이 맞습니다.
이럴 때는 아래처럼 최소 점검을 해보는 것이 좋습니다.
# 플러그인 활성화 시도
openclaw plugins enable telegram
# 게이트웨이 재시작
pkill -f "openclaw gateway"
openclaw gateway다만 환경마다 서비스 방식이 다르니, systemd로 돌리는 경우라면 실제 서비스 재시작 명령을 써야 할 수 있습니다. 이 부분은 설치 방법에 따라 달라집니다.
복붙용 완성 예시
아래 코드는 “일단 Telegram DM + 그룹 멘션 응답까지 한번에 테스트하고 싶다”는 분들에게 가장 무난한 시작점입니다.
{
"channels": {
"telegram": {
"enabled": true,
"botToken": "123456789:AAEXAMPLE_REPLACE_THIS",
"dmPolicy": "pairing",
"groups": {
"*": {
"requireMention": true
}
}
}
}
}저장 후 실행은 이렇게 하면 됩니다.
openclaw gateway그 다음 Telegram에서 내 봇에게 메시지를 보내고, pairing 승인까지 마치면 기본 DM 테스트가 가능합니다.
openclaw pairing list telegram
openclaw pairing approve telegram ABC123아쉬운 점이나 주의할 점
Telegram 연동은 생각보다 구조가 단순한 편이지만, 실제 체감상 쉬운 구간과 어려운 구간이 분명히 나뉩니다. 토큰 발급 자체는 쉽지만, 그 다음부터는 OpenClaw 버전 차이와 문서 갱신 속도 때문에 예전 명령어를 따라 했다가 막히는 경우가 생길 수 있습니다. 특히 검색 결과에서 오래된 글을 먼저 보고 따라가면 channels login telegram 쪽으로 들어가서 시간을 쓰기 쉽습니다. 최근 기준으로는 그 방식보다 JSON 설정 + gateway 실행 흐름이 더 안전합니다.
또 하나는 Telegram 쪽 privacy mode입니다. OpenClaw 설정이 맞아도 Telegram 자체 정책 때문에 그룹 메시지가 안 보일 수 있어서, 이 문제를 OpenClaw 버그로 오해하기 쉽습니다. 실제로는 Telegram 봇 설정과 그룹 재추가까지 같이 봐야 제대로 동작하는 경우가 많습니다.
정리
OpenClaw 채널 설정에 Telegram을 추가하는 핵심은 어렵지 않습니다. BotFather에서 받은 토큰을 channels.telegram.botToken에 넣고, enabled: true를 켠 뒤, openclaw gateway로 실행하면 기본 구조는 끝입니다. DM은 기본적으로 pairing 승인을 거치고, 그룹은 requireMention 같은 제한을 걸어두면 처음 운영하기가 훨씬 편합니다.
처음 하는 분이라면 가장 추천하는 방식은 “JSON에 직접 넣기 → gateway 실행 → Telegram에서 DM 보내기 → pairing approve” 순서입니다. 이 흐름만 이해해두면 이후에는 그룹 확장이나 webhook, 다중 계정 설정으로 넘어가도 덜 헷갈립니다.