Claude Code를 텔레그램으로 연동하기 (Windows 트러블슈팅 포함)

Claude Code에는 "Channels"라는 리서치 프리뷰 기능이 있습니다. 터미널을 붙잡고 있지 않아도 텔레그램으로 봇에게 메시지를 보내면, 실행 중인 Claude Code 세션이 메시지를 받아 작업을 수행하고 다시 텔레그램으로 답을 보내주는 방식입니다.

이 글은 실제로 Windows 환경에서 연동을 시도하며 겪은 오류들과 해결 과정을 순서대로 정리한 기록입니다.

---

사전 준비물

• Claude Code 설치 및 claude.ai 계정(또는 Console API 키)으로 로그인 완료
• Bun — 채널 플러그인이 Bun 스크립트로 동작하므로 필수
• Team/Enterprise 조직이라면 관리자가 Channels 기능을 미리 켜둬야 함

---

1단계. 텔레그램 봇 생성

텔레그램에서 @BotFather를 열고 /newbot 입력 → 봇 이름과 bot으로 끝나는 유저네임 설정 → 토큰 발급.

BotFather는 봇을 "만들 때"만 쓰는 관리자 봇입니다. 이후 실제로 메시지를 주고받는 건 여기서 만든 내 봇입니다.
헷갈리기 쉬운 부분이니 주의하세요.

---

2단계. 플러그인 설치

/plugin install telegram@claude-plugins-official

 

Marketplace "claude-plugins-official" not found 오류가 뜨면:

/plugin marketplace add anthropics/claude-plugins-official

 

설치 후:

/reload-plugins

---

🔧 오류 1 — EBUSY: resource busy or locked

 

Windows에서 마켓플레이스를 추가할 때 아래 같은 오류가 자주 발생합니다.

Error: EBUSY: resource busy or locked, rm 'C:\Users\<사용자명>\.claude\plugins\marketplaces\anthropics-claude-plugins-official'

 

이전 시도에서 남은 폴더를 git이나 다른 Claude Code 프로세스가 붙잡고 있어서 생기는 Windows 특유의 파일 잠금 문제입니다.

 

해결법

1. 실행 중인 Claude Code 세션을 모두 종료
2. 문제 폴더를 수동 삭제
3. 명령 재실행
4. 그래도 반복되면 백신 실시간 스캔이나 OneDrive 동기화 경로 문제일 수 있으니 .claude 폴더를 동기화 제외 목록에 추가

 

powershell

   Remove-Item -Recurse -Force "C:\Users\<사용자명>\.claude\plugins\marketplaces\anthropics-claude-plugins-official"

 

"사용 중" 메시지가 뜨면 작업 관리자에서 git.exe, node.exe, claude.exe를 종료 후 재시도

---

3단계. 토큰 설정

/telegram:configure <BotFather에서받은토큰>

 

~/.claude/channels/telegram/.env에 저장됩니다.

 

---

4단계. 채널 켜고 재시작

bash

claude --channels plugin:telegram@claude-plugins-official

 

정상적으로 켜지면 아래와 같은 안내가 뜹니다.

 

Channels (experimental) messages from plugin:telegram@claude-plugins-official inject directly in this session

 

이 터미널 창은 계속 열어둬야 봇이 응답합니다.

---

5단계. 페어링

텔레그램에서 내 봇에게 메시지(예: "안녕")를 보내면 6자리 페어링 코드가 와야 합니다. 받은 코드를:

/telegram:access pair <코드>

 

이후 본인 계정만 사용하도록 제한:

/telegram:access policy allowlist

---

🔧 오류 2 — 봇에게 메시지를 보내도 답장이 없음

/status로 확인해보니 채널 표시는 정상이었지만:

MCP servers: 1 need auth, 1 failed · /mcp

 

/mcp로 상세를 보니 텔레그램 MCP 서버 자체가 실패 상태였습니다.

 

Plugin:telegram:telegram MCP Server
Status: ✘ failed
Command: bun
Args: run --cwd .../telegram/0.0.6

 

원인: 텔레그램 채널은 내부적으로 Bun으로 실행되는데, Bun이 설치돼 있지 않으면 "Listening" 문구가 떠도 실제로는 텔레그램 API에 연결되지 않습니다. /status의 "Listening" 표시는 채널이 등록됐다는 뜻이지, 실제 연결이 살아있다는 보장은 아니었습니다.

 

해결 순서

 

1. Bun 설치 여부 확인

 

   bun --version

 

2. 없다면 설치

 

   powershell -c "irm bun.sh/install.ps1 | iex"

1. 터미널을 완전히 새로 열기 — 같은 창에서는 PATH가 갱신되지 않아 bun 명령을 계속 인식하지 못함
2. 새 터미널에서 bun --version으로 재확인
3. Claude Code를 새 터미널에서 다시 실행

   claude --channels plugin:telegram@claude-plugins-official

 

3. /mcp로 telegram 서버 상태가 ✘ failed에서 벗어났는지 재확인

---

 

🔧 오류 3 — Bun 설치 후에도 계속 ✘ failed

 

Bun을 나중에 설치한 경우, 플러그인 캐시가 Bun 없이 처음 받아졌다면 캐시가 꼬였을 가능성이 있습니다. 이 경우 시도해볼 것들:

• Claude Code 밖에서 플러그인 실행 명령을 직접 돌려 실제 에러 메시지 확인

  bun run --cwd C:/Users/<사용자명>/.claude/plugins/cache/claude-plugins-official/telegram/0.0.6 start

 

Claude Code 안의 요약된 상태창과 달리, 직접 실행하면 모듈 누락·권한 문제·토큰 오류 등 구체적인 에러가 그대로 출력됩니다.

• 플러그인 재설치

  /plugin uninstall telegram@claude-plugins-official
  /plugin install telegram@claude-plugins-official
  /reload-plugins

---

정리

텔레그램 연동 자체는 몇 개의 슬래시 명령으로 끝나는 간단한 설정이지만, Windows 환경에서는 아래 두 가지가 가장 흔한 걸림돌이었습니다.

1. 파일 잠금(EBUSY) — 남은 캐시 폴더를 다른 프로세스가 붙잡고 있는 문제
2. Bun 미설치/PATH 미반영 — 채널 플러그인이 Bun 위에서 동작하는데, Bun이 없거나 설치 직후 터미널을 새로 열지 않으면 조용히 실패

/status나 "Listening" 문구만 보고 정상이라 판단하지 말고, /mcp 명령으로 MCP 서버 상태를 한 번 더 확인하는 습관이 문제를 빨리 잡는 데 도움이 됩니다.

 

---

 

참고: Anthropic 공식 문서 code.claude.com/docs/en/channels