01 / 34

Week 06 · 실습 · 2026-08 최신 기준

Claude Code 채널(Channels)
텔레그램에서 내 컴퓨터의 Claude 부리기

텔레그램으로 한 줄 보내면, 집에 있는 내 컴퓨터의 Claude Code가 직접 파일을 고치고 명령을 실행한 뒤 결과를 텔레그램으로 답장합니다. 터미널 앞에 앉아 있을 필요가 없습니다.

① 봇 만들기② 플러그인 설치③ 토큰 등록④ --channels 재시작⑤ 페어링·잠그기

오늘의 완료 기준: 내 폰 텔레그램에서 “git status 확인해줘”를 보내면, 내 PC의 Claude가 실행하고 텔레그램으로 답장이 온다.

왜 하는가 · 한 장 요약

카페에서 커피 마시다가, 폰으로 코드를 고칩니다

지금까지

터미널 앞에 앉아야만 한다

Claude Code를 쓰려면 PC 앞에서 터미널 창을 열어야 합니다. 밖에 나가면 아무것도 못 시킵니다.

→

채널 연결 후

텔레그램이 곧 입력창이다

“package.json에 --coverage 플래그 추가해줘” 한 줄 → 집에 있는 맥북이 파일을 수정하고 “완료했어요” 답장.

현재 상태(2026-08): 리서치 프리뷰. 공식 지원 채널은 텔레그램 · 디스코드 · iMessage 세 가지입니다.

오늘의 지도 · 5단계

순서대로 다섯 단계만 하면 끝납니다

STEP 1

봇 만들기

텔레그램 BotFather에서 /newbot → 토큰 받기

STEP 2

플러그인 설치

Claude Code 안에서 telegram 플러그인 설치·활성화

STEP 3

토큰 등록

받은 토큰을 Claude Code에 알려주기

STEP 4

재시작

--channels 플래그를 붙여 새로 실행

STEP 5

페어링·잠그기

코드로 내 계정 승인 → 허용목록만 통과

가장 많이 막히는 지점 미리 예고: 2·3·5단계 명령어는 터미널이 아니라 Claude Code 세션 안에서 치는 슬래시 명령어입니다. 이걸 터미널에 치면 아무 일도 일어나지 않습니다. (17쪽에서 자세히)

SECTION 01 · 개념

채널(Channels)이 대체 뭔데?

한 문장: 이미 열려 있는 내 Claude Code 세션에 바깥 사건을 밀어 넣는 통로.

개념 ①

메신저 앱이 터미널 창을 대신합니다

기존 방식

터미널 창 = 입력창

PC에서 터미널을 열고 claude를 실행한 뒤, 그 창에 직접 타이핑합니다.

채널 방식

텔레그램 DM = 입력창

메신저로 보낸 메시지가 이미 열려 있는 내 Claude Code 세션에 그대로 도착하고, 작업이 끝나면 메신저로 답장이 옵니다.

착각 방지: 텔레그램이 Claude가 되는 게 아닙니다. 실제로 코드를 고치는 건 내 컴퓨터에서 돌고 있는 Claude Code이고, 텔레그램은 화면일 뿐입니다. 그래서 세션이 열려 있는 동안에만 메시지가 도착합니다 — 상시 운영하려면 백그라운드나 상시 터미널로 띄워 둬야 합니다.

개념 ② · 내부 구조

MCP 서버가 텔레그램과 Claude 사이의 다리 역할을 합니다

📱 텔레그램내가 메시지 전송

→

🤖 텔레그램 봇메시지 수신

→

🔌 채널 플러그인MCP 서버 = 다리

→

✦ Claude Code내 PC에서 작업

들어오는 길

텔레그램 → Claude

터미널에 ← telegram · 이름: 메시지 형태로 표시됩니다.

나가는 길

Claude → 텔레그램

Claude가 reply 도구를 호출합니다. 답장 본문은 터미널에 안 보이고 텔레그램에만 나타납니다.

MCP(Model Context Protocol) — Claude가 외부 도구와 대화하는 표준 규격입니다. 채널은 그 위에서 Claude가 묻지 않아도 먼저 들어오는 메시지를 다룹니다.

개념 ③ · 실제 동작 화면

연결되면 텔레그램 대화 목록에 결과가 이렇게 쌓입니다

—□✕

☰

검색

My Claude Assistant오후 2:02

나: package.json에 test 스크립트 추가해줘

봇: ✅ 추가 완료했습니다

개

#개발오후 2:52

나: git status 확인해서 알려줘

봇: 변경된 파일 3개입니다

배

#배포오후 3:13

나: 오늘 작업 커밋하고 푸시해줘

봇: 🚀 배포 완료 — 링크 보내드립니다

문

#문서오후 4:37

나: 회의록 정리해서 위키에 올려줘

봇: ✅ 3쪽 추가했습니다

알

#알림오후 7:37

CI 결과 자동 수신

봇: 빌드 성공 · 테스트 24건 통과

방 하나 = 작업 창 하나

그룹·토픽마다 별도의 대화가 됩니다. 주제를 나눠 두면 요청과 결과가 서로 섞이지 않습니다.

마지막 줄이 Claude의 답장

각 방의 맨 아래 줄이 봇이 보낸 결과입니다 — “추가 완료했습니다”, “배포 완료 — 링크 보내드립니다” 처럼 결론만 돌아옵니다.

실제 작업은 전부 내 컴퓨터에서 실행됩니다. 도구 호출 과정은 터미널에 남고, 텔레그램에는 결과만 도착합니다.

SECTION 02 · 준비물

시작하기 전에 확인할 것

하나라도 빠지면 중간에 반드시 막힙니다.

준비물 4가지

이 네 가지가 갖춰져 있어야 합니다

01 · 필수

최신 Claude Code

claude --version으로 확인. 채널 기능이 없으면 먼저 업데이트합니다. (실습 기준 v2.1.80 이상)

02 · 인증

claude.ai 계정 또는 Console API 키

Anthropic 인증이 필요합니다. Bedrock·Google Cloud·Microsoft Foundry 경유로는 사용 불가.

03 · 런타임

Bun

채널 플러그인이 Bun 스크립트입니다. bun --version이 실패하면 bun.sh에서 설치.

04 · 계정

텔레그램 계정

봇을 만들고 메시지를 주고받을 텔레그램 앱이 필요합니다.

순서 주의: 버전 확인을 건너뛰면 /plugin 명령어 자체가 없어서 “그런 명령어 없다”는 답만 돌아옵니다.

준비물 확인 · 터미널

버전을 확인하고, 없으면 그 자리에서 설치합니다

# ① 확인 — 명령 프롬프트 · PowerShell · Windows Terminal
claude --version
2.1.81 (Claude Code) ← 2.1.80 이상이면 통과

bun --version
1.3.x ← 이 줄이 안 나오면 Bun 없음

# ② Bun이 없을 때 — Windows (PowerShell)
powershell -c "irm bun.sh/install.ps1|iex"

# 또는 npm이 이미 있다면
npm install -g bun

# macOS · Linux
curl -fsSL https://bun.com/install | bash

설치 후

터미널을 새로 열고 bun --version을 다시 확인합니다. 기존 창은 PATH를 모릅니다.

윈도우 요구사항

Windows 10 버전 1809 이상이어야 설치됩니다.

나중에 올릴 때

bun upgrade 한 줄이면 최신으로 갱신됩니다.

왜 Bun이 필요한가: 채널 플러그인이 Bun 스크립트라서, Bun이 없으면 /plugin install 단계에서 막힙니다. Claude Code 버전이 낮으면 채널 관련 명령어 자체가 없습니다 — 둘 다 여기서 먼저 해결하고 넘어갑니다.

SECTION 03 · STEP 1

텔레그램 봇 만들기 (BotFather)

봇은 내 Claude Code와 텔레그램 사이를 연결해주는 중간 다리입니다.

Step 1-1 · BotFather 찾기

텔레그램 검색창에 @BotFather를 입력합니다

반드시 확인: 이름 옆에 파란색 체크 표시가 있는 공식 계정을 선택합니다. 비슷한 이름의 사칭 계정이 많습니다.

Step 1-2 · 새 봇 생성

BotFather 대화창에 /newbot을 보내면 두 가지를 물어봅니다

첫 번째 질문 · Name

봇의 표시 이름

대화 목록에 보이는 이름입니다. 한글도 되고 공백도 됩니다. 아무 이름이나 됩니다.

My Claude Assistant

두 번째 질문 · Username

봇의 유저네임

세계에서 유일해야 하고, 반드시 bot으로 끝나야 합니다. 이미 쓰는 이름이면 다시 물어봅니다.

my_claude_bot

실제 대화에서 “Sorry, this username is already taken.”가 뜨면 당황하지 말고 다른 이름을 다시 보내면 됩니다.

Step 1-3 · 실제 대화 화면

BotFather와의 대화는 이렇게 흘러갑니다

/newbot → 이름 → 유저네임(중복이면 재입력) → Done! 과 함께 토큰 발급

Step 1-4 · 토큰 복사

토큰은 봇의 비밀번호입니다

# BotFather가 알려주는 토큰의 형태 (예시 · 실제 값 아님)
123456789:AAHfiqksKZ8WxYzAbCdEfGhIjKlMnOpQrSt

# 앞의 숫자와 콜론(:)까지 전부 포함해서 복사합니다

해야 할 것

· 콜론 앞뒤 전체를 복사
· 메모장 대신 비밀번호 관리자에 보관
· 유출되면 BotFather에서 재발급

절대 하지 말 것

· 단톡방·강의 화면에 붙여넣기
· 캡처해서 공유
· 깃허브에 커밋

토큰을 가진 사람은 누구나 그 봇을 조종할 수 있습니다. BotFather 안내문에도 그대로 적혀 있습니다 — “it can be used by anyone to control your bot.”

SECTION 04 · STEP 2

Claude Code에서 플러그인 설치

여기서부터는 터미널로 돌아옵니다.

가장 많이 막히는 지점 · 꼭 읽기

터미널 명령어와 세션 안 슬래시 명령어는 다릅니다

A · 일반 터미널에서

셸 프롬프트 $ 또는 % 가 보이는 상태

claude --version
claude
claude --channels ...

B · Claude Code 세션 안에서

claude를 실행해 Claude와 대화 중인 상태

/plugin install ...
/reload-plugins
/telegram:configure ...
/telegram:access pair ...
/exit

슬래시(/)로 시작하면 B라고 외우면 됩니다. B를 터미널에 치면 “command not found”가 나고, A를 세션 안에 치면 Claude가 그냥 대화로 받아버립니다.

Step 2-1 · 설치

Claude Code를 실행한 뒤, 세션 안에서 설치합니다

# ① 일반 터미널에서 Claude Code 실행
claude

# ② 세션이 열리면 그 안에서 (슬래시 명령어)
/plugin install telegram@claude-plugins-official

설치 범위를 물어보면

user scope(사용자 범위)를 고르세요. 그래야 어느 프로젝트 폴더에서 켜도 채널이 붙습니다.

설치 요약 확인

Run /reload-plugins to activate. 가 보이면 그 명령을 반드시 실행해야 configure 명령이 생깁니다.

참고: 버전이 낮으면 Claude가 “Claude Code doesn't have a plugin system”이라고 답합니다. 명령어를 잘못 친 게 아니라 버전이 낮다는 신호입니다.

Step 2-2 · 실제 화면

설치 성공 화면과, 버전이 낮을 때의 화면

위쪽 = 구버전이라 플러그인 시스템이 없다는 답변 · 아래쪽 = 설치 성공 후 /reload-plugins 안내

Step 2-3 · 에러 대처 & 활성화

에러 문구를 그대로 읽고, 문구별로 대응합니다

# Marketplace "claude-plugins-official" not found → 마켓플레이스 추가 후 재시도
/plugin marketplace add anthropics/claude-plugins-official

# 목록이 오래됐을 때 → 갱신
/plugin marketplace update claude-plugins-official

# plugin not found in the marketplace → 플러그인 이름 오타 확인 후 재실행
/plugin install telegram@claude-plugins-official

설치 후 반드시

/reload-plugins

설치만으로는 동작하지 않습니다. 다시 불러와야 활성화됩니다.

SECTION 05 · STEP 3–5

토큰 등록 → 재시작 → 페어링

여기까지 하면 실제로 메시지가 오갑니다.

Step 3 · 봇 토큰 등록

아까 복사한 토큰을 Claude Code에 알려줍니다

# Claude Code 세션 안에서
/telegram:configure <토큰>

# 실제 예시
/telegram:configure 123456789:AAHfiqksKZ8WxYzAbCdEfGhIjKlMnOpQrSt

저장 위치

토큰은 아래 파일에 저장됩니다. 직접 열어서 수동으로 적어도 됩니다.

~/.claude/channels/telegram/.env

대안 · 환경변수

Claude Code를 켜기 전에 셸에서 TELEGRAM_BOT_TOKEN을 설정해 두는 방법도 공식 지원됩니다.

Step 3 · 실제 화면

Claude가 설정 순서를 직접 안내해 줍니다

◼ Windows PowerShell

—□✕

● 텔레그램 채널 설정 가이드입니다:

현재 상태:
- 토큰: 미설정
- 접근 정책: 기본값 (페어링 모드, 허용 목록 비어있음)

설정 순서:
1. 텔레그램에서 @BotFather에게 DM을 보냅니다
2. /newbot 명령어를 입력하고 안내에 따라 봇 이름을 정합니다
3. BotFather가 123456789:AAH... 형태의 토큰을 줍니다
4. 여기서 아래 명령어를 실행합니다:

/telegram:configure <받은 토큰>

토큰 설정이 끝나면 봇에게 DM을 보내 본인 계정을 연결하는 과정을 안내해 드리겠습니다.> /telegram:configure 865▮▮▮▮:AAE▮▮▮▮▮▮▮▮

인자 없이 /telegram:configure 만 치면 현재 상태 + 설정 순서를 알려줍니다

Step 3 · 상태 확인

등록 전 상태는 이렇게 보입니다

◼ Windows PowerShell

—□✕

Claude Code v2.1.81
Welcome back! Opus 4.6 (1M context) · Claude Max
> /telegram:configure Read 2 files (ctrl+o to expand)

● Here's your Telegram channel status:

Token: Not set
Access policy: Default (pairing mode, empty allowlist, no pending pairings)

Token: Not set / Access policy: Default (pairing mode, empty allowlist, no pending pairings) — 토큰을 등록하면 이 줄이 바뀝니다. 등록이 됐는지 헷갈릴 때 이 화면으로 확인하세요.

Step 4 · 채널 플래그로 재시작

이 플래그가 없으면 텔레그램과 절대 연결되지 않습니다

# ① 지금 열려 있는 세션을 종료 (세션 안에서)
/exit

# ② 터미널에서 --channels 플래그를 붙여 새로 시작
claude --channels plugin:telegram@claude-plugins-official

시작 화면에서 확인

채널 안내 문구가 뜹니다. 플러그인이 없거나 승인 목록에 없으면 그 아래 경고 한 줄로 이유를 알려줍니다.

이상하게 안 보이는 이유

프리뷰 기간이라 --channels는 claude --help에 안 나옵니다. 목록에 없어도 동작합니다.

토큰 등록만 하고 그냥 claude로 켜면 아무 반응이 없습니다. 반응이 없을 때 가장 먼저 볼 것이 이 플래그입니다.

Step 5 · 페어링

코드는 텔레그램에서 받고, 승인은 PC 세션에서 합니다

여기서 대부분 헷갈립니다. 두 곳을 오가는 단계라서 그렇습니다.

① 텔레그램 앱에서

봇에게 아무 메시지나 보냅니다

처음 보는 사용자라 봇이 페어링 코드를 답장으로 보내줍니다. 내가 코드를 입력하는 게 아니라 받는 겁니다.

답장이 없으면 PC에서 --channels로 안 켜진 것입니다.

→

② PC의 Claude Code 세션에서

받은 코드를 입력해 승인합니다

텔레그램이 아니라 터미널에서 돌고 있는 Claude Code 안에 칩니다. 승인되면 내 계정이 허용목록에 들어갑니다.

# ② PC의 Claude Code 세션 안에서 — 텔레그램에서 받은 코드로 승인
/telegram:access pair <코드>

# 그 다음, 내 계정만 통과하도록 잠급니다 (권장)
/telegram:access policy allowlist

코드는 만료됩니다. 실패하면 텔레그램에서 봇에게 다시 메시지를 보내 새 코드를 받으세요. 허용목록에 없는 사람의 메시지는 조용히 버려지고, 반대로 허용된 사람은 내 세션의 도구 승인까지 대신 눌러줄 수 있으니 정말 믿는 계정만 넣습니다.

권한 문제 · 두 가지 해법

밖에 있는데 터미널이 승인을 기다리면 아무것도 못 합니다

권장 · 권한 릴레이

승인 요청을 채팅으로 전달

권한 릴레이를 지원하는 채널은 승인 프롬프트를 메신저로 보내 원격에서 허용/거부를 누를 수 있습니다. 권한을 버리지 않는 방법입니다.

최후수단 · 무인 운용

묻지 않고 바로 실행

--dangerously-skip-permissions는 대부분의 확인을 건너뜁니다. 신뢰하는 환경에서만.

claude --channels plugin:telegram@claude-plugins-official --dangerously-skip-permissions

이름 그대로 “위험하게 권한을 건너뛴다”는 뜻입니다. 개인 노트북의 내 프로젝트면 몰라도, 회사 자산·공용 서버에서는 쓰지 않습니다. 이 모드에서도 자동 승인되지 않는 동작은 여전히 남아 있습니다.

SECTION 06 · 실전 & 한계

실제로 써보면 어떤 느낌인가

되는 것과, 아직 안 되는 것을 정확히 구분합니다.

실전 활용

평소 Claude Code에 하던 것처럼 그냥 보내면 됩니다

“package.json에 test 스크립트 추가해줘”

“src/utils.ts에 있는 타입 에러 고쳐줘”

“git status 확인해서 알려줘”

“오늘 작업한 내용 커밋하고 main에 푸시해줘”

사진도 보낼 수 있습니다

폰에서 에러 화면을 캡처해 봇에게 보내면 Claude가 이미지를 인식해 분석해 줍니다. 다만 텔레그램이 사진을 압축하므로, 원본 품질이 필요하면 길게 눌러 “파일로 보내기”를 선택하세요.

응용: 사람 메시지만이 아니라 CI 결과·에러 추적기·배포 웹훅도 같은 방식으로 밀어 넣어, Claude가 내 파일이 열려 있는 상태에서 바로 반응하게 만들 수 있습니다.

알아두면 좋은 것 · 현재 한계

지금은 아직 안 되는 것들

타이핑 표시

Claude가 작업 중이면 텔레그램에 “봇이름이 입력 중…”이라고 표시됩니다.

미지원

음성 메시지

현재 봇은 음성을 텍스트로 변환하지 못합니다. 텍스트로만 소통해야 합니다.

한계

메시지 히스토리 없음

텔레그램 봇 API 한계로 봇은 도착하는 순간에만 메시지를 봅니다. 맥락이 필요하면 직접 붙여넣어야 합니다.

주의

세션이 꺼지면 끝

세션이 열려 있을 때만 도착합니다. 상시 운영은 백그라운드·상시 터미널로 띄워 둬야 합니다.

# 여러 채널을 동시에 쓰려면 공백으로 구분
claude --channels plugin:telegram@claude-plugins-official plugin:discord@claude-plugins-official

문제 해결 체크리스트

막혔을 때 이 순서로 확인합니다

봇에 보냈는데 무반응

① --channels 플래그로 실행 중인가
② 페어링·허용목록에 내 계정이 있는가
③ 토큰이 ~/.claude/channels/telegram/.env에 들어갔는가

“plugin not found”

마켓플레이스를 add 또는 update 한 뒤 설치를 다시 시도합니다.

페어링 코드 실패

코드는 만료됩니다. 봇에게 다시 메시지를 보내 새 코드를 받습니다.

시작 화면에 경고가 뜬다

조직 승인 목록/채널 비활성화 문제입니다. 관리자에게 channelsEnabled 활성화를 요청합니다.

리서치 프리뷰라는 점을 감안하세요. 롤아웃이 순차 적용 중이고 --channels 문법도 바뀔 수 있습니다. 간혹 메시지가 씹히거나 연결이 불안정할 수 있습니다.

치트시트 · 전체 명령어 한눈에

처음부터 끝까지 순서대로

# 0. 준비 확인 (터미널)
claude --version | bun --version

# 1. 텔레그램 @BotFather 에서 /newbot → 토큰 복사

# 2. Claude Code 실행 (터미널)
claude

# 3~6. Claude Code 세션 안에서 실행하는 슬래시 명령어
/plugin install telegram@claude-plugins-official # user scope 선택
/reload-plugins
/telegram:configure <토큰>
/exit

# 7. 채널 플래그로 재시작 (터미널)
claude --channels plugin:telegram@claude-plugins-official

# 8. 텔레그램에서 봇에게 메시지 → 받은 코드로 승인 (세션 안)
/telegram:access pair <코드>
/telegram:access policy allowlist

# (선택) 무인 운용까지 포함한 최종 실행 명령어
claude --channels plugin:telegram@claude-plugins-official --dangerously-skip-permissions

이번 주 실습 · 합격 기준

직접 해보고, 증거 한 장을 남깁니다

기초 · 필수

① 내 봇 만들기 (BotFather)
② 플러그인 설치 + /reload-plugins
③ 토큰 등록
④ --channels로 재시작
⑤ 페어링 + allowlist로 잠그기
⑥ 폰에서 “git status 확인해줘” → 답장 받기

심화 · 선택

① 폰으로 에러 화면 캡처 보내고 분석받기
② 실제 파일 수정 지시 → 결과 확인
③ 커밋·푸시까지 원격으로 시켜보기
④ 디스코드 또는 iMessage 채널도 붙여보기
⑤ 내 업무에서 “밖에서 시키면 좋을 일” 3가지 적기

제출물: 텔레그램 대화 캡처 1장. 단 토큰이 보이는 화면은 절대 제출하지 않습니다. 토큰 부분은 가리거나, 대화 화면만 캡처하세요.

Week 06 마무리 · Week 07 준비

오늘은 ‘내 PC의 Claude’를 주머니 속으로 옮겼습니다

BotFather봇·토큰

→

Plugin설치·활성화

→

Configure토큰 등록

→

--channels재시작

→

Pair · Allowlist승인·잠금

Week 06 · 오늘

나 × Claude × 한 DM

이동 중에도 내 컴퓨터에 일을 시키는 개인 연결을 만들었습니다.

Week 07 · 다음

Hermes Agent

쓸수록 똑똑해지는 에이전트 — 사실은 기억으로, 절차는 스킬로 쌓아 어제 배운 것을 오늘 쓰게 만듭니다.

출처 — Anthropic 공식 문서 code.claude.com/docs/en/channels (2026-08-18 확인)

Claude Code 채널(Channels)텔레그램에서 내 컴퓨터의 Claude 부리기