OpenClaw Telegram 연동 튜토리얼: Bot 생성부터 설정 완료까지

브라우저를 열고 사이트에 로그인해 로딩을 기다리는 대신 Telegram에서 AI 어시스턴트에게 바로 질문하고 싶다면, OpenClaw와 Telegram Bot을 연동해 30분 안에 구현할 수 있습니다. 백엔드 개발 지식도 필요 없고 서버 설정을 걱정할 필요도 없습니다.

이 글에서는 BotFather로 Bot을 생성하고 Token을 받은 뒤 OpenClaw를 설정하고, 허용 목록 보안 정책을 적용해 테스트하는 전체 과정을 단계별로 설명합니다. 직접 겪은 시행착오와 자주 발생하는 문제의 해결 방법도 담았습니다. 30분이면 24시간 온라인 상태인 개인 AI 어시스턴트를 만들 수 있습니다.

저비용 ‘랍스터 키우기’ 가이드: ArkClaw로 AI Agent의 진입 장벽 낮추기

최근 큰 인기를 끄는 OpenClaw(랍스터)는 유용하지만 설정 과정이 너무 복잡한가요? ByteDance Volcano Engine의 ArkClaw는 진입 장벽을 크게 낮췄습니다. 서버와 Token 설정을 씨름할 필요 없이 한 번의 클릭으로 브라우저 제어, 스크립트 실행, 캘린더 관리까지 가능한 24시간 온라인 ‘AI 일꾼’을 만들 수 있습니다.

무엇보다 가격이 저렴합니다. 월 이용료는 9.9위안이며, 제 초대 코드 ZLKUK54M을 사용해 여기에서 가입하면 8.9위안입니다. 개발자라면 Coding Plan Pro에 가입해 무료로 사용할 수도 있습니다.

준비 사항: 먼저 알아야 할 기본 개념

시작하기 전에 몇 가지 핵심 개념부터 살펴보겠습니다. 지루한 이론이 아니라, 미리 이해하면 많은 시행착오를 줄일 수 있는 내용입니다.

Telegram Bot은 일반 계정이 아닙니다. 메시지를 받고 답장을 보낼 수 있지만 먼저 대화를 시작할 수는 없는 자동 응답 인터페이스에 가깝습니다. 고객 지원 챗봇처럼 사용자가 질문해야 답하는 방식입니다.

BotFather란 무엇인가요? Telegram이 공식 제공하는 ‘Bot 공장’으로, 모든 Bot은 여기에서 만들어집니다. BotFather 자체도 Bot이며, 대화를 통해 자신의 Bot을 생성하고 설정할 수 있습니다. 처음 들었을 때는 Bot으로 Bot을 관리한다는 점이 꽤 재미있었습니다.

OpenClaw는 어떤 역할을 하나요? 간단히 말해 Telegram과 AI 대규모 언어 모델을 연결하는 다리입니다. Telegram이 메시지를 받으면 OpenClaw가 이를 Claude나 GPT로 전달하고, AI의 답변을 다시 Telegram으로 보냅니다. 이 과정에서 코드를 전혀 작성할 필요가 없습니다.

다음 항목을 준비하세요:

• Telegram 계정 하나
• 설치되어 실행 중인 OpenClaw(아직 설치하지 않았다면 공식 문서나 제가 이전에 작성한 설치 튜토리얼을 참고하세요)
• AI 모델 API Key(Claude, GPT, Gemini 모두 가능하며, 먼저 무료 할당량으로 테스트해도 됩니다)

솔직히 이 준비 과정은 복잡하지 않습니다. OpenClaw는 Telegram, WhatsApp, WeCom 등 여러 플랫폼과 다양한 AI 모델을 지원하므로 한 번 설정한 뒤 모델을 바꾸기도 쉽습니다.

1단계: BotFather로 Telegram Bot 생성하기

이제 본격적으로 시작해 보겠습니다. Telegram을 열고 검색창에 @BotFather를 입력한 뒤 파란색 인증 배지가 있는 공식 계정을 선택하세요. 가짜 계정도 적지 않으니 잘못 선택하지 않도록 주의해야 합니다.

Bot 생성 대화 과정은 매우 간단합니다:

1. BotFather에 /newbot 명령을 보냅니다.
2. Bot의 표시 이름을 묻는 메시지가 나타나면 ‘나의 AI 어시스턴트’처럼 원하는 이름을 입력합니다.
3. 이어서 사용자 이름을 설정합니다. 반드시 bot으로 끝나야 하며 Telegram 전체에서 고유해야 합니다. 저는 처음에 AIAssistantBot을 사용하려 했지만 이미 선점되어 있어서 서너 번 시도한 끝에 성공했습니다.

‘사용자 이름이 이미 사용 중’이라는 메시지가 나타나면 숫자나 이름의 약자를 추가해 보세요. 예를 들어 MyAwesomeAI2024Bot처럼 만들 수 있습니다.

Bot Token을 받는 것이 가장 중요한 단계입니다. Bot 생성에 성공하면 BotFather가 다음과 같은 형식의 긴 문자열을 보내 줍니다.

123456789:ABCdefGHIjklMNOpqrsTUVwxyz1234567890

이 Token은 집 열쇠만큼 중요합니다. Token을 실수로 공개 GitHub 저장소에 커밋했다가 할당량을 모두 도용당해 수백 위안을 손해 본 사례도 봤습니다. 즉시 비밀번호 관리자나 암호화 메모에 복사해 두고, 채팅 기록이나 일반 클라우드 메모에는 절대 남기지 않는 것이 좋습니다.

선택 사항이지만 권장하는 설정:

• /setdescription으로 Bot 소개를 설정하면 사용자가 Bot을 열 때 볼 수 있습니다.
• /setabouttext로 ‘정보’ 내용을 설정합니다.
• /setuserpic으로 프로필 사진을 업로드하면 더 전문적으로 보입니다.

자신의 Telegram 사용자 ID도 반드시 확인하세요! 잠시 후 허용 목록을 설정할 때 필요합니다. Telegram에서 @userinfobot을 검색하고 /start를 보내면 123456789 같은 숫자 ID가 반환됩니다. 이것도 기록해 두세요.

2단계: OpenClaw의 Telegram Channel 설정하기

Bot Token을 받았다면 이제 OpenClaw를 설정할 차례입니다. 다소 기술적으로 보이지만, 사실상 JSON 파일 하나를 편집하는 작업입니다.

설정 파일을 찾습니다. 현재(2026년) OpenClaw의 기본 상태 디렉터리는 일반적으로 ~/.openclaw/이며 기본 설정 파일은 openclaw.json입니다. Telegram 필드 이름과 계층 구조는 공식 Telegram 채널 문서를 기준으로 확인하세요. 예전 자료에 나오는 ~/.clawdbot/config/channels.json은 이름 변경 전의 경로입니다. 아직 이전 디렉터리를 사용 중이라면 이 시리즈의 이름 변경 안내에 따라 먼저 이전하세요. Docker 배포에서는 마운트한 경로가 OPENCLAW_HOME / ~/.openclaw에 해당하는지 확인해야 합니다.

KiloClaw - 기업용 매니지드 OpenClaw, AI Agent 오케스트레이션 및 스마트 라우팅

시작하기 →광고

아래는 이해를 돕기 위한 예시입니다. 개인 사용자가 자신의 사용자 ID를 명시적으로 허용해 ‘페어링만 사용하는 방식’의 불확실성을 없앤 구성입니다. 실제 키 이름과 기본값(예: 기본 DM 정책은 흔히 pairing)은 공식 문서와 마법사가 생성한 파일을 기준으로 확인해야 하며, 오래된 배열 구조를 그대로 복사해서는 안 됩니다.

{
  "channels": {
    "telegram": {
      "enabled": true,
      "botToken": "YOUR_BOT_TOKEN_HERE",
      "dmPolicy": "allowlist",
      "allowFrom": [123456789]
    }
  }
}

필드 설명(공식 문서와 일치하는 핵심 사항):

• botToken: BotFather에서 복사한 Token입니다. 공백이나 줄바꿈이 들어가지 않도록 주의하세요.
• dmPolicy / allowFrom: Bot에게 개인 메시지를 보낼 수 있는 사용자를 제어합니다. 개인용이라면 allowlist와 자신의 숫자 ID를 함께 사용하는 편이 간단합니다. 공식 기본값인 pairing을 사용한다면 첫 개인 메시지 전송 시 Gateway에서 openclaw pairing approve telegram <CODE>를 실행해야 합니다. 자세한 내용은 공식 문서를 참고하세요.
• enabled: 해당 채널을 활성화할지 지정합니다.

이 파일은 어떻게 편집하나요?

Linux 또는 Mac을 사용한다면 다음 명령을 실행합니다.

nano ~/.openclaw/openclaw.json

Docker를 사용한다면 컨테이너에 들어가 마운트 디렉터리의 동일한 파일을 편집합니다. 컨테이너 내부 경로는 compose의 마운트 설정에 따라 달라집니다.

docker exec -it openclaw sh
vi /root/.openclaw/openclaw.json

또는 호스트에서 마운트 디렉터리의 파일을 직접 편집해도 됩니다.

자주 발생하는 오류:

• JSON 형식은 엄격합니다. 마지막 키-값 쌍 뒤에는 쉼표를 넣으면 안 됩니다.
• Token을 붙여넣을 때 따옴표나 공백을 함께 복사하기 쉬우므로 꼼꼼히 확인하세요.
• allowFrom은 배열입니다. 사용자가 한 명뿐이어도 배열 형식으로 작성해야 합니다. ID 형식은 공식 문서를 참고하세요.

처음 설정할 때 저도 쉼표를 하나 더 넣는 바람에 OpenClaw가 시작되지 않았고, 한참 로그를 확인한 뒤에야 원인을 찾았습니다. JSONLint 같은 온라인 JSON 형식 검사 도구를 사용하면 이런 단순한 오류를 피할 수 있습니다.

3단계: 허용 목록으로 Bot 보호하기

허용 목록은 정말 중요합니다. Bot Token이 실수로 유출되어 전 세계 누구나 내 Bot으로 AI 할당량을 소비할 수 있다고 생각해 보세요. 실제로 제 지인 중 한 명은 이런 일을 겪어 한 달치 Claude 할당량을 3일 만에 모두 소진했습니다.

허용 목록을 반드시 설정해야 하는 이유:

• 모르는 사람이 AI 할당량을 남용하는 것을 막습니다. 실제 비용과 직결되는 문제입니다.
• 민감한 정보 유출을 방지합니다. AI와의 대화에 업무 내용이 포함될 수 있습니다.
• 사용 비용을 통제할 수 있습니다. 특히 GPT-4처럼 비싼 모델을 사용할 때 중요합니다.

접근 정책은 어떻게 설정하나요? 앞에서 @userinfobot으로 확인한 사용자 ID를 기억하시나요? 공식 설정에서 개인 메시지에 흔히 사용하는 필드는 channels.telegram.allowFrom이며, dmPolicy와 함께 사용합니다.

단일 사용자(본인만 허용) 예시입니다. 이 필드는 channels.telegram 아래에 작성해야 합니다.

"dmPolicy": "allowlist",
"allowFrom": [123456789]

여러 사용자(팀):

"dmPolicy": "allowlist",
"allowFrom": [123456789, 987654321, 555555555]

다른 사람의 Telegram ID를 확인하는 방법:

1. 상대방에게 Telegram에서 @userinfobot을 검색하게 합니다. 공식 권장 방법은 먼저 내 Bot에 개인 메시지를 보낸 다음 openclaw logs --follow 로그에서 from.id를 확인하는 것입니다.
2. /start 명령을 보냅니다.
3. 반환된 숫자 ID를 전달받습니다.
4. 해당 ID를 allowFrom 배열에 추가합니다.

팀용으로 설정한다면 권한이 있는 모든 사용자의 ID와 이름을 문서에 기록해 두는 것이 좋습니다. 누군가 퇴사하면 즉시 허용 목록에서 제거해야 합니다. 이것이 기본적인 보안 관리입니다.

Pairing(페어링) 모드에 관하여:

Telegram DM의 공식 기본 정책은 흔히 pairing입니다. 처음 개인 메시지를 보낼 때 Gateway 머신에서 openclaw pairing approve telegram <CODE>를 실행해야 합니다. 이 튜토리얼처럼 ‘사용자 ID만으로 접근’하게 하려면 dmPolicy: "allowlist"를 사용하고 allowFrom을 명시하세요. 자세한 내용은 공식 문서를 참고하세요.

4단계: OpenClaw를 시작하고 연결 테스트하기

설정을 마쳤으니 이제 Bot이 정상적으로 작동하는지 확인할 차례입니다.

Gateway 시작하기:

로컬에 설치했다면(openclaw onboard --install-daemon을 실행한 경우 먼저 openclaw gateway status를 사용할 수 있습니다):

openclaw gateway
# 또는 설치된 시스템 서비스 사용:
openclaw gateway start

소스 코드 개발 모드로 시작하는 경우는 드뭅니다. 일반 사용자는 Gateway CLI를 기준으로 사용해야 하며, 공식 문서의 명령 대신 추측한 npm start를 사용하면 안 됩니다.

Docker로 배포했다면:

docker compose up -d

서비스 상태 확인하기:

시작 후 로그를 확인해 Telegram Channel이 정상적으로 로드되었는지 확인합니다. Docker를 사용한다면 다음 명령을 실행합니다.

docker compose logs openclaw -f

다음과 비슷한 로그가 보여야 합니다.

[INFO] Loading Telegram channel: telegram-main
[INFO] Telegram bot connected successfully
[INFO] Listening for messages...

오류 메시지가 표시되어도 당황하지 마세요. 오류 내용을 기록한 뒤 아래 문제 해결 목록을 확인하면 됩니다.

Alibaba Cloud - 개발자 클라우드 1순위, Lighthouse 서버 15% 할인

15% 할인 받기 →광고

첫 대화 테스트:

1. Telegram에서 생성할 때 지정한 bot으로 끝나는 Bot 사용자 이름을 검색합니다.
2. 채팅 창 아래의 Start 버튼을 누릅니다.
3. ‘안녕하세요’ 또는 ‘Hi there’ 같은 테스트 메시지를 보냅니다.
4. 모든 설정이 정상이면 몇 초 뒤 Bot이 AI가 생성한 답변을 보냅니다.

처음 Bot의 답변을 봤을 때는 저도 꽤 설렜습니다. 직접 만든 로봇이 실제로 대화를 나누는 듯한 느낌이었습니다.

Bot이 응답하지 않나요? 바로 재설치하지 말고 아래 문제 해결 목록을 먼저 확인하세요. 문제의 90%는 빠르게 해결할 수 있습니다.

자주 발생하는 문제 해결 목록

Bot이 응답하지 않거나 설정이 적용되지 않나요? 당황하지 말고 하나씩 확인해 보세요. 제가 겪었던 문제를 체크리스트로 정리했으며, 이 순서대로 살펴보면 대부분 해결할 수 있습니다.

문제 1: Bot이 어떤 메시지에도 전혀 응답하지 않음

가장 흔한 문제이며 원인은 여러 가지일 수 있습니다. 다음 순서대로 확인하세요.

• OpenClaw 서비스가 실행 중인가요? docker ps 또는 ps aux | grep openclaw로 확인하세요.
• Bot Token이 올바르게 설정되어 있나요? ~/.openclaw/openclaw.json의 channels.telegram.botToken에 불필요한 공백이나 따옴표가 없는지 확인하세요.
• 사용자 ID가 allowFrom에 있나요(allowlist 정책)? 또는 pairing을 완료했나요(pairing 정책)? @userinfobot이나 공식 권장 로그 방식으로 ID를 다시 확인하세요.
• 설정 파일의 JSON 형식이 올바른가요? JSONLint 온라인 도구로 확인하세요.
• AI 모델의 API Key가 유효하고 할당량이 남아 있나요? AI 서비스 제공업체의 관리 콘솔에서 잔액을 확인하세요.

문제 해결 명령:

# OpenClaw 로그 확인
docker compose logs openclaw -f

# 설정 파일 형식 확인
cat ~/.openclaw/openclaw.json | jq .

문제 2: ‘Unauthorized’ 또는 ‘Forbidden’ 오류가 표시됨

이 오류는 대부분 허용 목록 문제입니다. 다음 항목을 확인하세요.

• dmPolicy: "allowlist"를 사용할 때 Telegram 사용자 ID가 allowFrom에 있는지 확인합니다. 공식적으로 접두사가 붙은 문자열 형식도 허용되며 자세한 내용은 문서를 참고하세요.
• pairing을 사용한다면 Gateway에서 openclaw pairing approve telegram <CODE>를 실행했는지 확인합니다.
• 설정을 수정한 뒤 OpenClaw 서비스를 재시작했는지 확인합니다.

문제 3: Bot의 응답이 매우 느림

Bot의 답변이 너무 오래 걸린다면 다음과 같은 원인이 있을 수 있습니다.

• AI 모델 API의 응답이 느립니다. 특히 사용자가 몰리는 시간대에 발생할 수 있습니다.
• 네트워크 연결에 문제가 있습니다. 서버와 AI 서비스 제공업체 사이의 네트워크를 확인하세요.
• 서버 리소스가 부족합니다. CPU와 메모리 사용량을 확인하세요.

개선 방법:

• 응답 속도가 더 빠른 AI 모델로 바꿔 보세요.
• GPT-4를 사용 중이라면 GPT-3.5 또는 Claude 3 Haiku를 먼저 사용해 보세요.
• 서버 사양을 높이거나 네트워크를 최적화하세요.

문제 4: 설정 파일을 수정해도 적용되지 않음

저도 이 문제를 겪었습니다. 한참 설정을 수정했는데도 아무 변화가 없었던 이유는 서비스를 재시작하지 않았기 때문이었습니다.

해결 방법:

docker compose restart
# 또는
systemctl restart openclaw

문제 5: Bot의 대화 기록을 확인하는 방법

OpenClaw는 대화 기록을 로컬에 저장합니다. 다음과 같은 방법으로 확인할 수 있습니다.

• 로그 파일 확인(기본 경로)
• OpenClaw의 Control UI 사용(활성화한 경우)
• 데이터베이스 직접 확인(SQLite 또는 설정된 다른 데이터베이스)

문제 6: Bot Token이 유출된 경우

Token을 실수로 공개 저장소에 커밋했거나 외부에 노출했다면 다음과 같이 대응하세요.

1. 즉시 BotFather에서 /revoke 명령으로 Token을 폐기합니다.
2. /token 명령으로 새 Token을 생성합니다.
3. OpenClaw 설정 파일을 업데이트합니다.
4. 서비스를 재시작합니다.
5. AI 서비스 제공업체의 사용량을 확인해 오용 여부를 점검합니다.

고급 설정(선택 사항)

기본 기능만으로도 충분하지만 더 다양한 기능을 활용하고 싶다면 OpenClaw의 고급 설정을 살펴볼 수 있습니다.

환영 메시지와 명령 메뉴 설정하기:

BotFather에서 /setcommands를 사용해 다음과 같은 Bot 명령 메뉴를 설정할 수 있습니다.

start - 대화 시작
help - 도움말 보기
clear - 대화 기록 지우기

사용자가 /를 입력하면 이 명령들이 표시됩니다.

Railway - 현대적인 배포 플랫폼, 번거로운 운영 없이 몇 분 만에 라이브

지금 시작 →광고

DM 페어링 모드 활성화하기:

여러 사람이 사용하도록 하면서 허용 목록을 직접 관리하고 싶지 않다면 페어링 코드 모드를 사용할 수 있습니다.

"enableDmPairing": true

OpenClaw가 페어링 코드를 생성하며, 사용자는 처음 사용할 때 이 코드를 입력해 활성화할 수 있습니다. 다른 사람에게 서비스 형태로 제공할 때 적합합니다.

사용자별로 다른 AI 모델 설정하기:

OpenClaw는 사용자별로 서로 다른 AI 모델을 할당할 수 있습니다. 예를 들어 관리자는 GPT-4, 일반 사용자는 GPT-3.5를 사용하게 할 수 있습니다. 자세한 설정은 OpenClaw 공식 문서의 Multi-Model 섹션을 참고하세요.

OpenClaw Skills 연동하기:

Skills는 AI 어시스턴트가 다음과 같은 실제 작업을 수행하게 해 주는 OpenClaw의 핵심 기능입니다.

• 파일 관리(파일 생성, 읽기, 편집)
• Shell 명령 실행
• 웹 검색
• 코드 작성 및 디버깅

다만 Skills 기능, 특히 Shell 명령 실행은 보안 위험이 크므로 신중하게 활성화해야 합니다.

대화 메모리와 개인화 응답 설정하기:

OpenClaw는 대화 기록을 자동으로 저장합니다. 메모리 길이와 개인화 프롬프트 등을 설정해 AI 어시스턴트를 자신의 사용 습관에 더 잘 맞출 수 있습니다.

이 글에서는 고급 기능을 자세히 다루지 않겠습니다. 관심이 있다면 OpenClaw 공식 문서를 참고해 더 깊이 알아보세요.

결론

지금까지 살펴본 전체 과정은 생각보다 복잡하지 않습니다. BotFather로 Bot을 만들고 Token을 받은 뒤 OpenClaw를 설정하고 허용 목록을 구성해 테스트하는 데 30분이면 충분합니다.

가장 실수하기 쉬운 부분을 다시 정리하면 다음과 같습니다:

• Bot Token을 안전하게 보관하고 공개 저장소에 커밋하지 마세요.
• 허용 목록은 보안의 핵심이므로 편의를 위해 건너뛰면 안 됩니다.
• JSON 형식은 엄격하며 쉼표 하나만 더 있어도 설정에 실패할 수 있습니다.
• 설정을 변경한 뒤에는 반드시 서비스를 재시작해야 적용됩니다.

이 튜토리얼을 따라왔다면 이제 정상적으로 작동하는 Telegram AI 어시스턴트가 생겼을 것입니다. 브라우저를 열고 사이트에 로그인해 로딩을 기다릴 필요 없이 Telegram에서 언제든 질문할 수 있어 훨씬 편리합니다.

다음 단계로 할 수 있는 일:

• 여러 AI 모델을 사용해 보고 자신의 요구에 가장 잘 맞는 모델을 찾아보세요.
• OpenClaw의 Skills 기능을 살펴보고 AI 어시스턴트가 실제 작업을 수행하게 해 보세요.
• 유용하다면 팀원에게도 접근 권한을 설정해 주세요.

OpenClaw는 Telegram뿐 아니라 WhatsApp, WeCom 등의 플랫폼과도 연동할 수 있습니다. 이 설정 방법을 익히면 다른 플랫폼에도 같은 원리를 적용할 수 있습니다.

문제가 생겨도 당황하지 말고 위의 문제 해결 목록을 다시 보거나 OpenClaw 커뮤니티에 질문하세요. 이런 도구를 다루는 재미는 문제를 하나씩 해결할 때마다 새로운 것을 배운다는 데 있습니다.

이제 AI 어시스턴트와 대화를 시작해 보세요!