Claude Code Channels — 터미널 없이 텔레그램으로 코딩 시키는 시대 2/2

더 많은 글은 radarlog.kr에서.

---

1편에서 Channels가 뭔지, 왜 필요한지를 다뤘다. MCP가 클로드→외부 방향이었다면, Channels는 외부→클로드 방향이라는 얘기. 오픈소스로 해킹하는 것과 공식 플러그인 시스템의 차이도 짚었다.

이번 편에서는 진짜로 손을 더럽힌다. 텔레그램 봇을 만들고, 플러그인을 설치하고, 내 폰에서 클로드한테 코딩을 시키는 것까지.

텔레그램 봇부터 만든다

Channels의 첫 번째 공식 플러그인이 텔레그램이다. 텔레그램을 선택한 이유는 명확하다. 봇 API가 열려있고, 모바일에서 쓰기 편하고, 무료다. 게임 서버 운영할 때 디스코드 봇을 붙이는 것과 같은 맥락이다. 가장 접근성 좋은 메신저에 먼저 붙인다.

텔레그램을 열고 @BotFather를 검색한다. BotFather는 텔레그램 봇을 생성하고 관리하는 공식 봇이다. UE5로 치면 에디터에서 새 프로젝트를 만드는 것과 같다. 모든 건 여기서 시작한다.

BotFather한테 /newbot 명령을 보낸다. 봇 이름을 정하고, username을 정하면 API Token이 나온다. 이 토큰이 봇의 열쇠다. 게임 서버의 API Key와 같다. 이걸 잃어버리면 남이 내 봇을 조종할 수 있으니 절대 외부에 노출하면 안 된다.

/newbot
> 봇 이름: MyClaude_Dev_Bot
> username: my_claude_dev_bot
> 토큰: 7123456789:AAH_yourTokenHere...

토큰이 나오면 따로 저장해둔다. 다음 단계에서 바로 쓴다.

시작 전에 확인할 것

Channels는 아직 research preview 상태다. Claude Code v2.1.80 이상이 필요하고, claude.ai 로그인 필수다. Console이나 API key 인증으로는 안 된다. 그리고 런타임으로 Bun이 필요하다.

# 버전 확인
claude --version

# Bun 설치 (없으면)
curl -fsSL https://bun.sh/install | bash

게임 프로젝트에서 특정 SDK 버전과 빌드 툴이 맞아야 빌드가 되는 것처럼, 여기도 전제 조건이 있다. 이거 안 맞추고 시작하면 첫 단계에서 막힌다.

플러그인 설치와 토큰 등록

토큰을 받았으면 Claude Code 쪽을 세팅할 차례다.

먼저 Claude Code 세션을 하나 연다. 그 안에서 텔레그램 플러그인을 설치하고 토큰까지 등록한다. npm으로 패키지 설치하는 것과 비슷한 흐름이다.

# 세션 시작
claude

# 세션 안에서 플러그인 설치
/plugin install telegram@claude-plugins-official

# 토큰 등록
/telegram:configure 7123456789:AAH_yourTokenHere...

/plugin install이 뭘 하는 건지 뜯어보면, Claude Code 세션에 텔레그램 이벤트를 수신할 수 있는 어댑터를 등록하는 거다. 게임으로 치면 서버에 새로운 네트워크 프로토콜 핸들러를 등록하는 것과 같다. "이제 이 포맷의 패킷도 받을 수 있어"라고 선언하는 거다.

/telegram:configure는 토큰을 .claude/channels/telegram/.env에 저장한다. 이 파일을 직접 수정해도 되고, 쉘 환경변수 TELEGRAM_BOT_TOKEN으로 설정해도 된다. 쉘 환경변수가 우선이다.

채널 모드로 재시작

토큰까지 등록했으면 세션을 종료하고, 채널 플래그를 붙여서 다시 시작한다.

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

여기가 중요하다. .mcp.json에 서버가 등록돼 있어도 --channels에 명시적으로 플러그인 이름을 넣어야 메시지를 수신한다. UE5에서 bReplicates = true를 안 켜면 리플리케이션이 안 되는 것과 같다. 명시적으로 켜줘야 한다.

복수의 채널을 동시에 쓸 수도 있다. 스페이스로 구분하면 된다.

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

페어링과 보안 잠금

세션이 채널 모드로 떴으면, 텔레그램에서 내 봇한테 DM을 보낸다. 봇이 6자리 페어링 코드로 응답한다. 디스코드와 달리 텔레그램 봇은 서버 초대 같은 단계 없이 바로 DM이 된다.

텔레그램에서 봇한테 아무 메시지 → 봇이 6자리 코드 응답: A7X9K2
Claude 세션에서: /telegram:access pair A7X9K2
연결 성공

페어링이 끝나면 바로 allowlist로 잠근다. 이게 중요하다. 페어링 모드가 기본값인데, 이 상태에서는 아무나 봇한테 DM을 보내면 페어링 코드를 받을 수 있다. 내 ID가 등록된 뒤에는 allowlist로 전환해서 모르는 사람이 코드 응답을 받지 못하게 해야 한다.

/telegram:access policy allowlist

보안, 좀 더 신경 쓸 것

allowlist까지 걸었으면 기본적인 보안은 된 거다. 근데 더 챙길 게 있다.

클로드 세션이 어떤 권한으로 돌고 있는지. sudo 권한이 있는 상태에서 외부 입력을 받으면 위험하다. 텔레그램에서 "rm -rf /" 같은 걸 보내는 극단적인 경우까지는 아니더라도, 의도치 않은 시스템 변경이 생길 수 있다.

최소 권한 원칙을 지킨다. 클로드 세션은 프로젝트 디렉토리 안에서만 작동하게 범위를 잡는다. 게임 서버에서 샌드박스 안에 모드를 가두는 것과 같은 개념이다. Dedicated Server에서 RCON 포트를 열어두되 패스워드를 걸고 실행 가능한 명령어를 제한하는 것처럼.

그리고 하나 더. 클로드가 작업 중에 퍼미션 프롬프트를 만나면 — 예를 들어 파일 삭제 확인 같은 — 로컬 터미널에서 직접 승인해야 한다. 텔레그램에서 원격으로 승인이 안 된다. 이건 안전장치다. 자리를 비운 사이에 위험한 작업이 자동으로 승인되는 걸 막아준다.

실제로 써보면 이런 느낌이다

세팅이 끝난 뒤의 워크플로우를 그려보자.

집 PC에 클로드 세션이 --channels로 떠 있다. 프로젝트 디렉토리는 내가 작업 중인 UE5 프로젝트. 나는 퇴근해서 지하철에 타고 있다.

폰에서 텔레그램을 연다. 내 봇한테 메시지를 보낸다.

나: "PlayerController.cpp에서 GetPawn() 널 체크 빠진 부분 찾아서 수정해줘"

집 PC의 클로드가 이 메시지를 받는다. 해당 파일을 열고, GetPawn() 호출부를 전부 스캔하고, 널 체크가 없는 곳을 찾아서 수정한다. 결과를 텔레그램으로 돌려보낸다.

Claude: "PlayerController.cpp 3곳 수정했다. 
        Line 127: MoveToLocation()에서 GetPawn() 호출 전 널 체크 추가
        Line 243: ApplyDamage()에서 동일
        Line 891: RespawnPlayer()에서 동일
        커밋할까?"
나: "ㅇㅇ"
Claude: "커밋 완료. 메시지: 'fix: add null checks for GetPawn() calls'"

지하철에서 폰 몇 번 터치한 것뿐인데 로컬 코드가 수정되고 커밋까지 됐다. 예전 같았으면 집에 가서 노트북 열고, 에디터 키고, 하나하나 찾아서 고쳐야 했을 거다.

이게 Channels의 실제 사용 감각이다. SSH 터널도 없고, 원격 데스크톱도 없다. 그냥 메신저로 대화하듯이.

커스텀 채널 — 텔레그램 말고 내가 만든다

텔레그램은 공식 플러그인이 있어서 편하다. 근데 모든 팀이 텔레그램을 쓰는 건 아니다. 사내 메신저가 따로 있을 수도 있고, 특정 웹훅에 반응하게 만들고 싶을 수도 있다.

앤스로픽은 이걸 위해 Channels Reference를 공개했다. 직접 채널 어댑터를 만들 수 있는 스펙 문서다.

핵심은 간단하다. 클로드 세션이 기대하는 이벤트 포맷에 맞춰 데이터를 쏘면 된다. 텔레그램 플러그인도 내부적으로는 텔레그램 봇 API의 메시지를 이 포맷으로 변환해서 클로드 세션에 전달하는 거다. 플러그인은 결국 프로토콜 어댑터다.

게임 개발로 치면, 서버가 받는 패킷 포맷이 정해져 있고, 클라이언트가 그 포맷에 맞춰 보내기만 하면 되는 구조다. 텔레그램 클라이언트든, 디스코드 클라이언트든, 자체 웹 대시보드든 — 포맷만 맞추면 전부 연결할 수 있다.

커스텀 채널의 구조:

[외부 이벤트 소스] → [커스텀 어댑터] → [표준 이벤트 포맷] → [Claude 세션]

이게 열리면 시나리오가 확 넓어진다.

사내 CI 서버가 빌드 실패하면 자동으로 에러 로그를 클로드 채널에 던진다. Jira 티켓이 "In Progress"로 바뀌면 해당 티켓의 설명을 클로드한테 보내서 구현 시작을 트리거한다. GitHub PR에 리뷰 코멘트가 달리면 클로드가 코멘트를 읽고 수정 사항을 반영한다.

전부 웹훅 → 어댑터 → 클로드 세션 파이프라인이다.

게임 라이브 서비스에서 운영 자동화를 위해 슬랙 봇이나 사내 대시보드에 서버 명령을 연결하는 것과 정확히 같은 패턴이다. 서비스 운영을 해본 사람이라면 이 파이프라인이 얼마나 강력한지 바로 체감된다.

참고 문서는 Channels Reference에 있다. 스펙 전체가 공개돼 있으니, 사내 메신저나 슬랙에 연결하는 어댑터를 만드는 건 시간 문제다.

한 가지 주의할 점. research preview 기간에는 커스텀 채널이 승인된 allowlist에 포함되지 않는다. 로컬에서 테스트하려면 --dangerously-load-development-channels 플래그를 써야 한다. 이름부터 위험하다는 걸 알려주는 플래그니까, 프로덕션에서는 쓰면 안 된다.

텔레그램 연동 전에 채널 개념 자체를 먼저 맛보고 싶다면 fakechat 데모가 있다. 로컬에서 돌아가는 채팅 UI로, 채널의 푸시 로직을 브라우저에서 바로 테스트해볼 수 있다.

/plugin install fakechat@claude-plugins-official
claude --channels plugin:fakechat@claude-plugins-official
# http://localhost:8787 에서 채팅

전체 셋업 플로우 정리

처음부터 끝까지 한 번에 보면 이렇다.

# 0. 전제 조건: Claude Code v2.1.80+, Bun 런타임, claude.ai 로그인

# 1. 텔레그램에서 @BotFather로 봇 생성 → 토큰 받기

# 2. Claude Code 세션 열기
claude

# 3. 세션 안에서 텔레그램 플러그인 설치
/plugin install telegram@claude-plugins-official

# 4. 토큰 등록
/telegram:configure 7123456789:AAH_yourTokenHere...

# 5. 세션 종료 후 채널 모드로 재시작
claude --channels plugin:telegram@claude-plugins-official

# 6. 텔레그램에서 봇한테 DM → 6자리 페어링 코드 수신 → 세션에서 pair

# 7. 보안 잠금
/telegram:access policy allowlist

# 8. 완료 — 텔레그램에서 메시지를 보내면 Claude가 실행

7단계다. 복잡해 보이지만 실제로 하면 5분이면 끝난다. BotFather에서 봇 만드는 게 가장 오래 걸리고, 나머진 명령어 복붙이다.

이게 바꾸는 것

1편에서 MCP + Channels = 양방향 통신이라고 했다. 2편에서 실제로 세팅해보니 더 확실해진다. 이건 단순히 "원격으로 코딩 시키기"가 아니다.

개발자의 인터페이스가 바뀐다. 터미널이 유일한 입구였던 시대가 끝난다. 메신저가 입구가 되고, 웹훅이 입구가 되고, CI 파이프라인이 입구가 된다. 클로드 세션은 항상 켜져 있는 개발 에이전트가 되고, 우리는 가장 편한 채널로 그 에이전트와 대화한다.

게임 서버가 처음에는 콘솔 창에서만 조작할 수 있었다가, RCON이 붙고, 웹 대시보드가 붙고, 디스코드 봇이 붙으면서 운영이 완전히 달라진 것처럼. 클로드도 같은 경로를 밟고 있다.

"터미널은 하나의 채널일 뿐이다. 이제 문이 여러 개다."