Claude Code에 Telegram·Discord 채널 연결하는 법 (Channels 설정 가이드)

TL;DR – Claude Code Channels는 실행 중인 로컬 Claude Code 세션에 Telegram/Discord 메시지를 push하는 기능이다. – 연결 흐름은 거의 동일하다: Bot/App 생성 → plugin 설치 → configure → --channels 재실행 → pair → allowlist. – 실전 운영에서는 Bun PATH, 토큰 파일 권한(chmod 600), always-on 세션(tmux/systemd), 비용/동시성 관리까지 같이 봐야 한다.

2026년 3월 기준으로 Claude Code Channels는 아직 research preview 상태지만, 이미 꽤 실용적입니다. 핵심은 단순히 “메신저에서 Claude를 부른다”가 아니라, 이미 실행 중인 로컬 Claude Code 세션에 외부 메시지를 직접 밀어 넣는 구조라는 점입니다.

즉, 내 PC나 서버에서 Claude Code가 돌아가고 있을 때:

Telegram DM으로 질문 보내기
Discord 봇으로 메시지 보내기
같은 채널로 답변 다시 받기
개인 운영용 원격 제어 흐름 만들기

같은 방식이 가능합니다.

이 글은 공식 문서 기준으로 Telegram/Discord 연결 방법, pairing + allowlist 보안 설정, 실서비스에서 자주 막히는 지점, 그리고 always-on 운영 팁까지 한 번에 정리한 가이드입니다.

시작 전에 알아야 할 것

Channels를 쓰기 전에 꼭 알고 있어야 할 전제가 있습니다.

Claude Code v2.1.80 이상 필요
claude.ai 로그인 필요
API key 인증만으로는 사용 불가
Team / Enterprise는 관리자가 channelsEnabled를 켜야 함
메시지는 세션이 살아 있는 동안만 들어옴
상시 사용하려면 Claude Code를 tmux / screen / systemd 같은 방식으로 계속 띄워둬야 함

한 줄로 요약하면:

Channels는 “항상 켜져 있는 내 Claude Code 세션에 외부 메시지를 push하는 기능”이다.

기존 방식과 뭐가 다른가

1) Claude Code on the web와 다름

웹에서 새 작업을 띄우는 방식은 새 클라우드 샌드박스에 가깝습니다.

반면 Channels는:

이미 열려 있는 내 로컬 세션에
현재 파일/컨텍스트가 살아 있는 상태로
메시지를 바로 주입합니다.

2) 일반 MCP와도 다름

일반 MCP 서버는 Claude가 필요할 때 읽으러 가는 구조에 가깝습니다.

Channels는 반대로:

외부 시스템이 먼저 메시지를 보냄
Claude Code 세션이 그걸 받아서 반응함

즉 polling보다 push에 더 가깝습니다.

어떤 채널을 지원하나

공식 문서 기준 research preview 단계에서 안내하는 채널은 다음과 같습니다.

Telegram
Discord
fakechat (로컬 테스트용)

실서비스 연결 전에 먼저 흐름을 확인하려면 fakechat부터 테스트하는 게 가장 안전합니다.

공통 준비물

Telegram과 Discord는 세부 설정은 다르지만, 실제 흐름은 거의 같습니다.

필수 준비물

Claude Code 설치 및 로그인 완료
Bun 설치
Claude Code 플러그인 마켓 접근 가능 상태
채널을 붙일 세션을 실행할 수 있는 로컬 PC 또는 서버

Bun 확인

bun --version

에러가 나면 Bun부터 설치해야 합니다. 공식 문서에서도 채널 플러그인은 Bun 기반 플러그인 런타임을 전제로 설명합니다.

서버에서 자주 놓치는 것: PATH

로컬 터미널에서는 잘 되는데 tmux, systemd, cron, 원격 셸에서만 플러그인이 실패하는 경우가 있습니다. 이때는 Bun 경로가 PATH에 빠진 경우가 많습니다.

예를 들어 tmux/systemd 환경에서는 아래처럼 Bun 경로를 명시적으로 넣어두는 편이 안전합니다.

export PATH="$HOME/.bun/bin:$PATH"

또는 systemd 서비스 파일을 쓴다면 Environment=PATH=... 형태로 넣어두는 방식이 더 안정적입니다.

가장 먼저 해볼 것: fakechat으로 구조 확인

외부 메신저를 붙이기 전에 fakechat으로 구조를 먼저 확인하면 실패 확률이 크게 줄어듭니다.

1) fakechat 플러그인 설치

Claude Code 안에서:

/plugin install fakechat@claude-plugins-official

플러그인을 못 찾는다면:

/plugin marketplace update claude-plugins-official

또는 처음 추가하는 상태라면:

/plugin marketplace add anthropics/claude-plugins-official

2) 채널 켜서 Claude Code 재실행

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

3) 브라우저에서 메시지 보내기

문서 기준 fakechat UI 주소는 아래입니다.

http://localhost:8787

여기서 메시지를 보내면 실행 중 Claude Code 세션으로 이벤트가 들어옵니다.

포트 8787이 이미 사용 중이라면 fakechat 테스트가 바로 안 될 수 있습니다. 이 경우 포트 충돌 여부를 먼저 확인하세요.

이 단계가 잘 되면 Telegram/Discord로 넘어가면 됩니다.

공통 설정 흐름 한 번에 보기

Telegram이든 Discord든 실제 흐름은 아래 5단계로 거의 동일합니다.

플랫폼에서 Bot/App 생성
Claude Code에서 plugin 설치
/<platform>:configure <token>으로 토큰 등록
claude --channels ...로 세션 재실행
DM으로 pairing code 수신 → pair → allowlist 적용

즉, 아래 구조를 한 번 머리에 넣고 가면 훨씬 덜 헷갈립니다.

Bot 만들기
→ plugin 설치
→ configure
→ --channels 재실행
→ pair
→ allowlist

아래부터는 Telegram/Discord별 차이점만 보면 됩니다.

Telegram 연결 방법

Telegram은 개인 사용자가 가장 빠르게 붙이기 좋습니다. 휴대폰에서 바로 DM처럼 쓸 수 있고, pairing + allowlist까지 걸면 비교적 안전하게 운영할 수 있습니다.

1) BotFather에서 텔레그램 봇 만들기

Telegram에서 BotFather를 열고:

/newbot

를 보냅니다.

그 다음:

봇 표시 이름 지정
bot으로 끝나는 username 지정
발급된 bot token 복사

2) 플러그인 설치 → 토큰 등록 → 세션 재실행

/plugin install telegram@claude-plugins-official
/reload-plugins
/telegram:configure <token>

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

토큰을 파일로 저장했다면 권한은 아래 보안 가이드의 chmod 600 예시대로 잠가두는 편이 안전합니다.

3) pair + allowlist

Telegram에서 봇에게 아무 메시지나 보내면 pairing code가 옵니다.

그 다음 Claude Code에서:

/telegram:access pair <code>
/telegram:access policy allowlist

공통 흐름 다시 보기

/plugin install <platform>@claude-plugins-official
/reload-plugins
/<platform>:configure <token>

claude --channels plugin:<platform>@claude-plugins-official

/<platform>:access pair <code>
/<platform>:access policy allowlist

Discord 연결 방법

Discord는 개인 DM도 가능하지만, 보통은 운영 서버 / 팀 서버 / 이벤트 브리지 용도로 더 잘 맞습니다.

1) Discord Developer Portal에서 앱/봇 만들기

Discord Developer Portal에서:

New Application
앱 이름 지정
Bot 섹션에서 봇 생성
Reset Token 후 토큰 복사

2) Message Content Intent 켜기

봇 설정의 Privileged Gateway Intents에서:

Message Content Intent 활성화

이걸 안 켜면 메시지를 제대로 읽지 못할 수 있습니다.

참고로 봇이 100개 이상의 서버에 들어가는 규모가 되면 Discord 쪽 별도 검증/심사가 필요할 수 있습니다. 개인용·소규모 운영에선 보통 큰 문제 없지만, 팀/엔터프라이즈 확장 시에는 미리 알고 가는 게 좋습니다.

3) 봇을 서버에 초대하기

OAuth2 > URL Generator에서:

bot scope 선택

그리고 최소 권한:

View Channels
Send Messages
Send Messages in Threads
Read Message History
Attach Files
Add Reactions

을 체크해 초대 링크를 생성합니다.

4) 플러그인 설치 → 토큰 등록 → 세션 재실행

/plugin install discord@claude-plugins-official
/reload-plugins
/discord:configure <token>

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

토큰을 파일로 저장했다면 권한은 아래 보안 가이드의 chmod 600 예시대로 잠가두는 편이 안전합니다.

5) pair + allowlist

Discord에서 봇에게 DM을 보내면 pairing code가 옵니다.

그 다음 Claude Code에서:

/discord:access pair <code>
/discord:access policy allowlist

공통 흐름 다시 보기

/plugin install <platform>@claude-plugins-official
/reload-plugins
/<platform>:configure <token>

claude --channels plugin:<platform>@claude-plugins-official

/<platform>:access pair <code>
/<platform>:access policy allowlist

자주 막히는 지점

1) plugin 설치는 됐는데 봇이 응답 안 함

가장 흔한 원인:

--channels 없이 세션 실행
세션 종료됨
/reload-plugins 안 함

2) plugin not found in marketplace

먼저 실행:

/plugin marketplace update claude-plugins-official

또는:

/plugin marketplace add anthropics/claude-plugins-official

3) Team / Enterprise인데 왜 안 되지

관리자 쪽 channelsEnabled 확인 필요.

설정 위치는 문서 기준:

claude.ai → Admin settings → Claude Code → Channels
또는 managed settings의 channelsEnabled: true

4) pair는 됐는데 운영이 불안함

아래까지 꼭 해두는 게 좋습니다.

/telegram:access policy allowlist

또는

/discord:access policy allowlist

보안 가이드

allowlist는 사실상 필수

공식 문서 기준 Channels는 sender allowlist 구조를 전제로 설명합니다.

핵심은:

--channels로 세션을 열고
pair 된 sender만 허용하고
allowlist로 잠그는 것

즉,

봇을 만든 것보다 더 중요한 건 누가 그 세션에 메시지를 넣을 수 있느냐입니다.

토큰 파일 권한

채널별 .env 파일은 토큰이 들어가므로 권한을 최소화하는 편이 안전합니다.

chmod 600 ~/.claude/channels/telegram/.env
chmod 600 ~/.claude/channels/discord/.env

권한 승인 문제

Channels를 붙였다고 해서 완전 무인 자동화가 되는 건 아닙니다.

Claude가 작업 중 아래 같은 상황을 만나면:

파일 수정
시스템 명령 실행
외부 접근
권한 승인 필요 작업

세션이 터미널 승인 대기 상태로 멈출 수 있습니다.

운영 가이드

always-on 운영

상시 사용하려면 결국 Claude Code 세션을 계속 살아 있게 유지해야 합니다.

headless 승인 대기 주의

서버에서 headless로 오래 켜두는 세션은 편하지만, 실제 작업 중에는 권한 승인 대기(approval gate) 때문에 멈출 수 있습니다. 예를 들어 파일 수정, 시스템 명령 실행, 외부 접근처럼 민감한 작업이 나오면 채널 메시지는 들어왔는데 세션은 승인 프롬프트 앞에서 대기 상태가 됩니다.

그래서 운영할 때는 보통 아래 중 하나로 정리합니다.

사람이 붙어 있는 supervised 세션으로 운영
permission relay를 지원하는 채널/구조 사용
완전 무인 환경에서만 제한적으로 --dangerously-skip-permissions 검토

마지막 옵션은 빠르지만 위험하므로, 개인 노트북이나 민감한 서버에서는 기본값으로 두지 않는 편이 안전합니다.

비용/토큰 관리

원격 채널에서 긴 작업을 던지면, 사용자가 터미널을 보지 않는 상태에서 예상보다 큰 토큰 비용이 나갈 수 있습니다.

그래서 실전 운영에서는:

먼저 짧은 질의응답부터 시작
긴 작업은 명시적으로 요청
always-on 세션에는 비용 경고/사용 규칙 정해두기

정도가 안전합니다.

세션 충돌 주의

로컬 터미널에서 직접 입력 중인데 Telegram/Discord 메시지가 들어오면, 입력 컨텍스트가 섞일 수 있습니다.

혼자 쓰는 개인 서버라도 아래 중 하나를 추천합니다.

Channels 전용 세션을 따로 띄우기
tmux에서 작업 세션 / 채널 세션 분리
중요한 작업 중엔 원격 입력을 잠시 끄기

CI/CD·컨테이너 환경 팁

컨테이너나 CI/CD처럼 파일 시스템 상태가 자주 바뀌는 환경에서는 .env 파일만 믿기보다 런타임 환경변수 주입 방식이 더 표준적이고 관리하기 쉽습니다.

퀵스타트 요약

/plugin install telegram@claude-plugins-official
/reload-plugins
/telegram:configure <token>
/telegram:access pair <code>
/telegram:access policy allowlist

claude --channels plugin:telegram@claude-plugins-official
chmod 600 ~/.claude/channels/telegram/.env

Discord

/plugin install discord@claude-plugins-official
/reload-plugins
/discord:configure <token>
/discord:access pair <code>
/discord:access policy allowlist

claude --channels plugin:discord@claude-plugins-official
chmod 600 ~/.claude/channels/discord/.env

fakechat

/plugin install fakechat@claude-plugins-official

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

브라우저 접속:

http://localhost:8787

결론

Claude Code Channels는 “메신저에서 Claude를 부르는 기능” 정도로 설명하면 반만 맞습니다.

정확히는:

실행 중인 로컬 Claude Code 세션에
외부 메시지나 이벤트를 push하고
필요하면 같은 채널로 다시 답변까지 보내게 만드는 기능입니다.

그래서 특히 잘 맞는 용도는 아래입니다.

외출 중 휴대폰에서 내 Claude Code 세션에 질문하기
Telegram/Discord를 개인 운영 채널로 쓰기
원격 이벤트 기반 자동화 만들기
팀 서버에서 간단한 이벤트 브리지 운영하기

반대로, 완전히 새 작업을 클라우드 샌드박스에서 맡겨 돌리는 방식을 원한다면 Channels보다 Claude Code on the web 쪽이 더 맞습니다.

참고 문서

Claude Code Channels 공식 문서: https://code.claude.com/docs/en/channels
Discord Developer Portal: https://discord.com/developers/applications
BotFather: https://t.me/BotFather

@welltip

정리를 위해 작성하는 개인노트

RSS 연락처