클로드 코드 텔레그램 연동, 휴대폰으로 내 컴퓨터를 원격 제어하는 2가지 방법과 보안 체크리스트

클로드 코드 텔레그램 연동은 Anthropic 공식 Channels 텔레그램 플러그인을 쓰는 방법이 가장 쉽습니다. 봇을 만들고 플러그인을 설치해 --channels로 실행하면, 휴대폰 텔레그램 메시지를 내 컴퓨터의 Claude Code가 받아 처리하고 답장합니다. 직접 만들려면 텔레그램 Bot API와 claude -p를 묶으면 되며, 어느 쪽이든 컴퓨터와 Claude Code가 켜져 있어야 하고 허용한 사람만 명령하도록 잠가야 합니다.

Channels는 2026년 3월 리서치 프리뷰(연구용 시험판)로 보도된 기능입니다. 이후 휴대폰에서 도구 실행을 승인하는 권한 중계가 추가됐지만, 출시 직후 설명 글에는 빠진 경우가 많습니다. 이 글은 2026년 10월 18일 공식 문서 기준으로 정리했습니다.

핵심 요약

가장 쉬운 길: 공식 Channels 텔레그램 플러그인 (Claude Code 2.1.80 이상, Bun 필요)
직접 구현: Bot API 롱 폴링 → 보낸 사람 ID 확인 → claude -p 실행 → sendMessage 회신
공통 조건: 컴퓨터와 Claude Code를 켜 두고, 허용 목록으로 내 계정만 받기
텔레그램이 꼭 필요하지 않다면 Remote Control도 선택지

1. 전체 구성: 휴대폰 텔레그램 → 봇 → 내 컴퓨터의 Claude Code → 결과 회신

텔레그램 원격 제어는 네 칸으로 이어집니다.

휴대폰 텔레그램: 봇에게 “테스트 돌려 줘”처럼 보냅니다
텔레그램 봇: 메시지가 텔레그램 서버에 쌓입니다
내 컴퓨터의 Claude Code: 새 메시지를 가져와 보낸 사람을 확인하고 작업합니다
결과 회신: 결과가 같은 봇을 통해 휴대폰으로 돌아옵니다

3번에서 컴퓨터가 텔레그램 서버에 새 메시지를 물어보며 기다리는 방식을 롱 폴링(getUpdates)이라고 합니다. 컴퓨터가 바깥으로 요청만 보내므로 공유기 포트를 열거나 공개 주소를 만들 필요가 없습니다.

휴대폰 텔레그램에서 봇을 거쳐 컴퓨터의 클로드 코드가 보낸 사람 ID를 확인해 작업하고 결과를 회신하는 구성도 — 클로드 코드 텔레그램 연동 전체 구성

2. 방법 1: 공식 Channels 텔레그램 플러그인 5단계 설정

채널(Channels)은 실행 중인 Claude Code 세션에 외부 메시지를 밀어 넣는 기능입니다. 2026년 10월 18일 기준 리서치 프리뷰에는 텔레그램, 디스코드, iMessage가 들어 있습니다.

시작 전 요구 사항

Claude Code 2.1.80 이상 (2026-10-18 기준 최신 2.1.302)
Bun 런타임
claude.ai 로그인 또는 Console API 키 인증
Team·Enterprise 조직은 관리자(Owner)가 켜야 함

Pro·Max 개인 사용자는 조직 설정 없이 세션마다 --channels로 켜면 됩니다. Amazon Bedrock, Google Cloud Agent Platform, Microsoft Foundry 인증에서는 쓸 수 없고, 무료 플랜 지원 여부는 공식 문서에 적혀 있지 않습니다. Bun은 다음 명령으로 설치합니다.

curl -fsSL https://bun.sh/install | bash

1단계: BotFather로 봇 만들기

봇은 텔레그램 공식 봇 관리 계정인 @BotFather에서 만듭니다. 실제 화면 기준으로 순서를 보면 다음과 같습니다.

① BotFather 대화 시작 — 텔레그램 검색창에서 @BotFather(파란 인증 배지가 있는 계정)를 찾아 시작을 누릅니다.

텔레그램 BotFather 시작 화면 — BotFather 대화 시작 화면

② /newbot 선택 — 메뉴의 명령어 목록에서 /newbot을 고르거나 직접 입력합니다.

BotFather 명령어 목록에서 /newbot 선택 — BotFather 명령어 목록 — /newbot이 새 봇 만들기

③ 이름과 사용자명 입력 — 표시 이름을 보낸 뒤 bot으로 끝나는 사용자명을 보내면 완료 메시지와 함께 HTTP API 토큰이 나옵니다. 사용자명은 5~32자의 영문·숫자·밑줄이며 나중에 바꿀 수 없습니다.

BotFather 봇 생성 완료 메시지 (토큰·봇 주소 가림) — 봇 생성 완료 메시지 — 토큰과 봇 주소는 가림 처리

토큰은 봇을 마음대로 조종할 수 있는 비밀번호와 같습니다. 화면 캡처나 깃 저장소에 노출됐다면 BotFather에서 /revoke로 바로 재발급하세요.

2단계: 플러그인 설치

claude
# Claude Code 안에서 입력 (설치 범위는 user scope 권장)
/plugin install telegram@claude-plugins-official

마켓플레이스가 없다는 오류가 나오면 /plugin marketplace add anthropics/claude-plugins-official을, 플러그인을 못 찾으면 /plugin marketplace update claude-plugins-official을 먼저 실행하세요.

3단계: 봇 토큰 등록

/telegram:configure <YOUR_BOT_TOKEN>

토큰은 ~/.claude/channels/telegram/.env에 저장됩니다. 셸 환경변수 TELEGRAM_BOT_TOKEN이 있으면 그 값이 먼저 적용됩니다.

4단계: 채널을 켜고 다시 실행

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

이때부터 플러그인이 봇 메시지를 폴링합니다. --channels는 claude --help에 나오지 않지만 작동하며, 프리뷰 기간에는 문법이 바뀔 수 있습니다.

5단계: 페어링하고 allowlist로 잠그기

페어링은 내 텔레그램 계정을 허용 목록에 넣는 절차입니다. 봇에게 아무 메시지나 보내면 6자리 코드가 오고, 그 코드를 Claude Code에 입력합니다.

/telegram:access pair <페어링_코드>
/telegram:access policy allowlist

두 번째 명령이 잠금입니다. 목록에 없는 사람의 메시지는 조용히 버리고 페어링 코드도 보내지 않습니다. 허용 목록은 숫자 사용자 ID로 ~/.claude/channels/telegram/access.json에 저장됩니다.

휴대폰에서 Allow/Deny로 권한 승인

Claude가 Bash 실행이나 파일 수정처럼 승인이 필요한 작업을 하려 하면, 공식 플러그인이 허용 목록의 개인 대화로 ‘Allow’, ‘Deny’ 버튼이 달린 요청을 보냅니다. 이 권한 중계는 Claude Code 2.1.81에서 추가됐고, 터미널과 휴대폰 중 먼저 답한 쪽이 적용됩니다.

공식 Channels 흐름 한눈에 보기 (PlantUML)

휴대폰 텔레그램 메시지가 봇과 플러그인을 거쳐 Claude Code 세션에 전달되고 권한 승인과 답장이 돌아오는 시퀀스 다이어그램 — 공식 Channels 텔레그램 플러그인 흐름 (클릭하면 크게 보기)

PlantUML 소스 보기

@startuml
title 공식 Channels 텔레그램 플러그인 흐름
skinparam shadowing false
skinparam defaultFontName "Apple SD Gothic Neo"
actor "나 (휴대폰)" as U
participant "텔레그램 봇\n(텔레그램 서버)" as T
participant "텔레그램 플러그인\n(내 컴퓨터)" as P
participant "Claude Code 세션\n(--channels 실행 중)" as C
U -> T : 메시지 보내기
P -> T : getUpdates (롱 폴링)
T --> P : 새 메시지
P -> P : 보낸 사람 ID가\nallowlist에 있는지 확인
alt 허용 목록에 없음
  P -> P : 조용히 버림
else 허용된 사용자
  P -> C : 채널 이벤트로 전달
  C -> C : 작업 수행 (파일 읽기·명령 실행)
  opt 승인이 필요한 도구 실행 (권한 중계)
    C -> P : 권한 요청
    P -> T : Allow / Deny 버튼 메시지
    T -> U : 승인 요청 표시
    U -> T : Allow 또는 Deny
    T --> P : 응답
    P --> C : 승인 결과 전달
  end
  C -> P : 답장 (reply)
  P -> T : sendMessage
  T -> U : 결과 표시
end
@enduml

3. 방법 2: claude -p 텔레그램 봇 직접 구현

claude -p는 대화 화면 없이 명령 한 줄로 Claude Code를 실행하고 결과만 출력하는 헤드리스 모드입니다. n8n이나 cron 같은 자동화와 묶기 쉽고, 프리뷰 문법 변경의 영향을 받지 않습니다.

토큰 보관: BotFather 토큰을 환경변수에 둡니다
롱 폴링과 발신자 확인: getUpdates로 받고, message.from.id가 내 ID가 아니면 버립니다
Claude 실행: claude -p --output-format json에 허용 도구를 최소로 지정합니다
회신: result 값을 sendMessage로 보내고, session_id는 다음 메시지의 --resume에 씁니다

내 숫자 ID는 봇에게 메시지를 보낸 뒤 아래 주소 응답의 from.id에서 확인합니다.

curl "https://api.telegram.org/bot<YOUR_BOT_TOKEN>/getUpdates"

파이썬 예시 코드 (표준 라이브러리만 사용)

import json, os, subprocess, urllib.parse, urllib.request

TOKEN = os.environ["TELEGRAM_BOT_TOKEN"]        # <YOUR_BOT_TOKEN>
ALLOWED_ID = int(os.environ["MY_TELEGRAM_ID"])  # 내 숫자 사용자 ID
API = f"https://api.telegram.org/bot{TOKEN}/"
WORKDIR = os.path.expanduser("~/bot-workspace")

def call(method, **params):
    data = urllib.parse.urlencode(params).encode()
    with urllib.request.urlopen(API + method, data, timeout=70) as r:
        return json.load(r)["result"]

def ask_claude(text, sid):
    cmd = ["claude", "-p", text, "--output-format", "json",
           "--allowedTools", "Read,Bash(git diff *)",
           "--permission-mode", "dontAsk"]
    if sid:
        cmd += ["--resume", sid]
    p = subprocess.run(cmd, cwd=WORKDIR, capture_output=True, text=True)
    if p.returncode != 0:
        return "실행 실패: " + p.stderr[-500:], sid
    out = json.loads(p.stdout)
    return out["result"], out["session_id"]

offset, sid = 0, None
while True:
    for u in call("getUpdates", offset=offset, timeout=50):  # 롱 폴링
        offset = u["update_id"] + 1
        msg = u.get("message") or {}
        if msg.get("from", {}).get("id") != ALLOWED_ID or "text" not in msg:
            continue  # 허용하지 않은 발신자는 버림
        reply, sid = ask_claude(msg["text"], sid)
        for i in range(0, len(reply), 4000):  # 4096자 제한 때문에 분할
            call("sendMessage", chat_id=msg["chat"]["id"], text=reply[i:i + 4000])

이 예시는 읽기와 git diff로 시작하는 명령만 허용합니다. dontAsk는 승인이 필요한 요청을 모두 거부하는 모드로, 공식 문서가 잠근 스크립트용으로 소개합니다. 파일 수정까지 맡기려면 Edit를 더하되 작업 폴더를 따로 두세요.

직접 구현 흐름도 (PlantUML)

getUpdates 롱 폴링으로 메시지를 받아 보낸 사람 ID를 확인하고 claude -p를 실행해 sendMessage로 회신하는 활동 다이어그램 — claude -p 직접 구현 흐름 (클릭하면 크게 보기)

PlantUML 소스 보기

@startuml
title claude -p 직접 구현 흐름 (롱 폴링)
skinparam shadowing false
skinparam defaultFontName "Apple SD Gothic Neo"
start
repeat
  :getUpdates(offset, timeout=50) 호출;
  if (보낸 사람 from.id가 내 ID인가?) then (예)
    :claude -p "<메시지>"
    --allowedTools "Read,Bash(git diff *)"
    --permission-mode dontAsk
    --output-format json (--resume 세션 ID);
    if (종료 코드 0?) then (예)
      :result를 4000자씩 나눠 sendMessage;
    else (아니오)
      :"실행 실패" 메시지를 sendMessage;
    endif
  else (아니오)
    :메시지 무시;
  endif
  :offset = update_id + 1;
repeat while (봇 프로그램 실행 중)
stop
@enduml

직접 구현할 때 주의할 점

--bare: 훅·플러그인·MCP·CLAUDE.md 자동 로딩을 건너뛰는 스크립트용 모드이며, 구독 로그인 대신 ANTHROPIC_API_KEY가 필요합니다
작업 폴더 설정: --bare 없이 -p를 쓰면 작업 폴더의 훅과 .mcp.json 서버를 신뢰 확인 없이 실행합니다
소비자 하나: 공식 플러그인 소스 주석에 따르면 토큰 하나로 getUpdates를 받는 프로그램은 하나뿐이고, 둘째가 폴링하면 409 오류가 납니다

4. 어떤 방식을 고를까요? 공식 Channels vs 직접 구현 vs Remote Control

처음이라면 공식 Channels가 맞습니다. 페어링, 허용 목록, 승인 버튼이 기본으로 들어 있습니다.

Remote Control은 Claude 모바일 앱이나 claude.ai/code에서 내 컴퓨터의 Claude Code 세션을 이어서 조작하는 공식 기능입니다. claude --remote-control이나 세션 안의 /remote-control로 시작합니다.

항목	공식 Channels	직접 구현	Remote Control
휴대폰 앱	텔레그램	텔레그램	Claude 앱·브라우저
인증	claude.ai 또는 API 키 (프리뷰)	로그인 또는 API 키	구독 플랜만, API 키 불가
보안 기본값	페어링·허용 목록	발신자 확인 직접 구현	claude.ai 계정
휴대폰 승인	Allow/Deny 버튼	허용 범위 미리 지정	앱에서 그대로
추천 대상	빠르게 시작하려는 분	자동화와 묶으려는 분	텔레그램이 필요 없는 분

세 방식 모두 컴퓨터가 바깥으로 요청을 보내는 구조라 외부 포트를 열지 않습니다. 다만 직접 구현에서 웹훅을 쓰면 공개 HTTPS 주소가 필요합니다.

5. 텔레그램 봇 원격 제어 보안 체크리스트 6가지

텔레그램 봇에는 누구나 메시지를 보낼 수 있습니다. 공식 문서는 발신자를 거르지 않는 채널을 프롬프트 인젝션(남의 문장으로 AI에게 엉뚱한 작업을 시키는 공격) 통로로 봅니다.

TIP 1. 봇 토큰은 코드 밖에 두세요
토큰이 있으면 누구든 봇을 조종할 수 있습니다. 유출이 의심되면 BotFather의 /token으로 새로 발급하세요.

TIP 2. 페어링 직후 allowlist로 잠그세요
공식 플러그인 정책은 pairing, allowlist, disabled 세 가지입니다. 내 계정을 등록했다면 바로 allowlist로 바꿉니다.

TIP 3. 보낸 사람 ID(from.id)로 거르세요
chat은 대화방, from은 보낸 사람으로 서로 다른 값입니다. 그룹에서는 둘이 달라지므로 from.id를 확인해야 합니다.

TIP 4. 허용 도구와 권한 모드를 최소로 정하세요
--dangerously-skip-permissions는 신뢰하는 환경에서만, bypassPermissions는 인터넷이 없는 컨테이너·VM에서만 쓰라고 공식 문서가 경고합니다. 승인 권한이 생기는 허용 목록에도 믿는 사람만 넣으세요.

TIP 5. 상시 사용 조건을 먼저 정하세요
메시지는 세션이 열려 있을 때만 도착합니다. 컴퓨터가 꺼지거나 세션이 닫히면 명령을 받지 못하므로 켜 둘 시간과 실행 폴더를 정하세요.

TIP 6. 웹훅을 쓴다면 HTTPS와 secret_token을 함께 쓰세요
웹훅은 텔레그램이 내 HTTPS 주소로 메시지를 보내 주는 방식이며, 포트는 443, 80, 88, 8443만 지원합니다. secret_token을 설정하면 요청마다 확인용 헤더가 붙습니다.

텔레그램 봇 원격 제어 보안 체크리스트 6가지 도식 — 텔레그램 봇 원격 제어 보안 체크리스트

6. 알아 둘 한계: 원격에서는 내 컴퓨터의 세션을 새로 켤 수 없습니다

텔레그램이든 Claude 앱이든, 휴대폰은 내 컴퓨터에서 이미 실행 중인 Claude Code 세션에 말을 거는 창구입니다. 컴퓨터에서 claude 프로세스가 돌고 있지 않으면 휴대폰에서 내 컴퓨터의 파일이나 프로그램을 다룰 방법이 없습니다. 공식 문서 기준으로 정리하면 다음과 같습니다.

원격 지시는 열려 있는 세션으로만 전달됩니다: Channels 메시지는 세션이 열려 있을 때만 도착합니다. 공식 문서도 상시 사용하려면 백그라운드 프로세스나 계속 켜 둔 터미널에서 실행하라고 안내합니다.
Remote Control도 같은 구조입니다: 공식 문서는 웹·모바일 화면을 로컬 세션을 들여다보는 창이라고 설명합니다. 컴퓨터가 켜져 있고 claude 프로세스가 계속 실행 중이어야 하며, 터미널을 닫거나 프로세스를 끝내면 세션이 오프라인이 됩니다.
휴대폰에서 새로 시작한 세션은 클라우드에서 돌아갑니다: Claude 앱이나 claude.ai/code에서 새로 연 Claude Code 세션(클라우드 세션)은 Anthropic 클라우드 환경에서 실행되므로 내 컴퓨터의 파일, MCP 서버, 프로그램을 쓰지 못합니다. 내 컴퓨터의 자원은 그 컴퓨터에서 연 세션만 쓸 수 있습니다.
서버 모드도 켜 둔 프로세스가 전제입니다: 내 컴퓨터에서 claude remote-control(서버 모드)을 실행해 두면 휴대폰에서 새 세션을 만들 수 있습니다. 하지만 그 서버 프로세스가 먼저 실행 중이어야 하고, 네트워크가 약 10분 넘게 끊기면 서버 모드 프로세스는 종료됩니다.

그래서 원격 제어의 출발점은 컴퓨터를 켜 두고, 그 컴퓨터에서 세션을 미리 열어 두는 것입니다. 원격 서버에서 실행한다면 공식 문서 권장대로 tmux나 screen 안에서 실행해 SSH 연결이 끊겨도 세션이 남게 하세요. 노트북이 잠자기에서 깨어나면 Remote Control은 자동으로 다시 연결됩니다.

7. 운영 메모: 알림 봇은 사용 중, 명령 받기는 다음 단계

이 블로그를 운영하는 저는 iMac에서 n8n과 Claude Code(claude -p)로 블로그 글 작성 자동화를 돌리고 있습니다. 2026년 10월 17일 BotFather로 봇을 만들어, 자동화 결과와 로그인 풀림 알림을 Bot API sendMessage(curl)로 휴대폰에 받고 있습니다.

텔레그램에서 컴퓨터로 명령을 보내는 쪽은 아직 구성하지 않았고, 다음 단계로 이 글의 방법을 적용할 계획입니다. 준비하며 확인한 점은 텔레그램 봇 하나에 웹훅이 하나뿐이고, 웹훅이 걸린 봇은 getUpdates를 쓸 수 없다는 것입니다. 그래서 n8n 텔레그램 트리거(웹훅)와 Channels 플러그인(폴링)은 봇을 나눠 쓰는 편이 안전해 보입니다. 공식 문서 두 곳을 함께 읽고 내린 판단이며, 직접 시험한 결과는 아닙니다.

자주 묻는 질문

Q. 클로드 코드 텔레그램 연동 공식 기능이 있나요?
있습니다. Claude Code Channels의 공식 텔레그램 플러그인이며 2026년 10월 18일 기준 리서치 프리뷰입니다. Claude Code 2.1.80 이상과 Bun이 필요합니다.

Q. 컴퓨터를 꺼도 텔레그램으로 명령할 수 있나요?
할 수 없습니다. 메시지는 세션이 열려 있을 때만 도착합니다. 받지 못한 메시지는 텔레그램 서버에 24시간까지만 남습니다.

Q. 다른 사람이 내 봇에 명령하면 어떻게 되나요?
허용 목록에 없는 발신자의 메시지는 조용히 버려집니다. allowlist로 잠그면 페어링 코드 회신도 하지 않습니다.

Q. Remote Control과는 무엇이 다른가요?
Remote Control은 Claude 앱이나 웹에서 내 세션을 조종하고, Channels는 텔레그램 같은 메신저의 메시지를 세션에 넣습니다. Remote Control은 API 키 인증을 지원하지 않습니다.

정리

처음이라면 공식 Channels 플러그인부터 설정해 보세요

클로드 코드 텔레그램 연동은 공식 플러그인 설치 후 페어링과 allowlist 잠금까지 마치는 것이 가장 빠르고 안전합니다. 자동화와 묶어야 할 때 claude -p 직접 구현으로 넓히고, 허용 도구는 최소로 두고 시작하시기 바랍니다.

이 글은 2026년 10월 18일 공식 문서 확인 기준입니다. Channels는 리서치 프리뷰라 명령어가 바뀔 수 있으니 설치 전 아래 문서를 확인하세요.

참고 자료

Claude Code Docs – Push events into a running session with channels (2026-10-18 확인)
Claude Code Docs – Channels reference (2026-10-18 확인)
anthropics/claude-plugins-official – telegram README (2026-10-18 확인)
anthropics/claude-plugins-official – telegram ACCESS.md (2026-10-18 확인)
anthropics/claude-plugins-official – telegram server.ts (2026-10-18 확인)
anthropics/claude-code CHANGELOG (2026-10-18 확인)
Claude Code Docs – Run Claude Code programmatically (2026-10-18 확인)
Claude Code Docs – Choose a permission mode (2026-10-18 확인)
Claude Code Docs – Remote Control (2026-10-18 확인)
Claude Code Docs – Claude Code on the web (cloud sessions) (2026-10-18 확인)
Telegram Bot API (2026-10-18 확인)
Telegram Bot Features (2026-10-18 확인)
Telegram Bots FAQ (2026-10-18 확인)
n8n Docs – Telegram Trigger common issues (2026-10-18 확인)
VentureBeat – Anthropic just shipped an OpenClaw killer called Claude Code Channels (2026-03-19 보도, 2026-10-18 확인)