Claude Code ↔ Telegram 브리지

Claude Code용 세션 고정형 Telegram 브리지입니다. 봇은 터미널 세션이 유지되는 동안만 살아 있습니다 — 시작하고, 사용하고, 종료하면 끝입니다. 상시 실행 데몬이 아닙니다.

공식 Claude Code Telegram 채널 플러그인의 포크로, 보안 패치와 tmux + Tailscale 기반 휴대용 배포 구성을 포함합니다.

작동 방식

Phone (Telegram)
  │
  ▼
┌─────────────────────┐
│  server.ts           │  Standalone MCP HTTP server
│  Polls Telegram      │  Runs as a systemd user unit
│  Queues messages     │  Starts/stops with the pin
└──────────┬──────────┘
           │ SSE (/events)
           ▼
┌─────────────────────┐
│  proxy.ts            │  Stdio MCP proxy
│  Bridges to Claude   │  Spawned by Claude Code
│  Owns the pin lock   │  One session at a time
└──────────┬──────────┘
           │ stdio
           ▼
┌─────────────────────┐
│  Claude Code         │  Your session
│  Reads messages      │  Calls reply/react/edit
│  Full tool access    │  Permission buttons in TG
└─────────────────────┘

핀 설계: 한 번에 하나의 Claude 세션만 봇을 소유할 수 있습니다. tgpin이 잠금 파일을 획득하고 폴러를 시작하며, 세션이 종료되면 둘 다 해제합니다. 이는 두 개의 폴러가 동일한 Telegram 토큰을 두고 경쟁할 때 발생하는 409 Conflict를 방지합니다.

보안 패치

업스트림 플러그인에는 정보 노출 문제가 있습니다: /start, /help, /status 명령이 접근 게이트 실행 전에 등록됩니다. dmPolicy: "allowlist" 모드에서 봇을 발견한 낯선 사람은 "Claude Code 브리지"임을 설명하는 친절한 응답을 받게 되며, 봇의 존재와 용도가 노출됩니다.

패치 내용: commandMuted() 가드를 추가했습니다. allowlist 또는 disabled 모드에서는 allowlist에 없는 사용자의 명령을 조용히 무시합니다. pairing 모드에서는 정상 작동합니다(/start가 새 사용자가 페어링을 배우는 방법이기 때문).

+15줄, 삭제 없음, git diff에서 확인 가능합니다.

설치

사전 요구 사항

• Claude Code CLI 설치

• Bun 런타임

• @BotFather에서 발급받은 Telegram 봇 토큰

1. 서버 설치

mkdir -p ~/.claude/telegram-server
cp server.ts proxy.ts package.json ~/.claude/telegram-server/
cd ~/.claude/telegram-server && bun install

2. 봇 토큰 설정

mkdir -p ~/.claude/channels/telegram
echo "TELEGRAM_BOT_TOKEN=YOUR_TOKEN_HERE" > ~/.claude/channels/telegram/.env
chmod 600 ~/.claude/channels/telegram/.env

3. systemd 사용자 유닛 설치

mkdir -p ~/.config/systemd/user
cp telegram-mcp.service ~/.config/systemd/user/
systemctl --user daemon-reload

서비스를 활성화하지 마세요 — tgpin이 자동으로 시작하고 중지합니다. 활성화하면 봇이 영구적으로 실행되어 핀 설계와 충돌합니다.

4. 런처 설치

cp tgpin ~/bin/tgpin
chmod +x ~/bin/tgpin

# Optional: alias in your .bashrc
echo 'alias tg="~/bin/tgpin"' >> ~/.bashrc

5. 접근 잠금 (권장)

기본적으로 봇은 pairing 모드입니다 — DM을 보내는 모든 사람이 페어링 코드를 받습니다. 자신의 Telegram 사용자 ID로 잠그려면:

cat > ~/.claude/channels/telegram/access.json << 'EOF'
{
  "dmPolicy": "allowlist",
  "allowFrom": ["YOUR_TELEGRAM_USER_ID"],
  "groups": {},
  "pending": {}
}
EOF

사용자 ID는 Telegram에서 @userinfobot에게 메시지를 보내면 확인할 수 있습니다.

사용법

세션 시작

tg              # start Claude with Telegram bridge
tg --continue   # resume the last conversation

휴대용 접근 (tmux + Tailscale + Termius)

이것의 진짜 가치는 휴대폰에서 SSH로 실행하는 것입니다. 구성 요소:

• Tailscale — 메시 VPN. 휴대폰과 머신이 사설 네트워크에서 서로를 볼 수 있으며, 포트 포워딩이나 공인 IP가 필요 없습니다. 개인 사용은 무료입니다.

• Termius — Android/iOS용 SSH 클라이언트. 키 인증, 영구 세션, Tailscale 주소를 지원합니다. 무료 티어로 충분합니다.

• tmux — 터미널 멀티플렉서. SSH 연결이 끊겨도 세션이 유지됩니다.

# On your machine (once):
tmux new -s claude
tg

# Detach: Ctrl+B, then D

# From your phone (Termius → Tailscale IP):
ssh your-machine
tmux attach -t claude

tmux 세션이 존재하는 한 봇은 계속 살아 있습니다. SSH 연결이 끊겨도 봇은 죽지 않습니다. tmux 세션을 닫으면 봇도 종료됩니다 — 의도된 설계입니다.

작업 흐름: 버스 안에서 휴대폰으로 Termius를 열고, Tailscale을 통해 머신에 SSH로 접속하고, tmux 세션에 연결하면 — Claude가 Telegram에서 활성화됩니다. Termius를 닫아도 tmux 세션은 유지되고 봇은 계속 실행됩니다. 나중에 어디서든 다시 연결할 수 있습니다.

권한 처리

도구 호출은 Telegram에서 승인/거부 버튼으로 표시됩니다. 세션은 --permission-mode default로 실행되므로, 파괴적인 작업(파일 쓰기, 셸 명령)은 실행 전에 명시적인 탭 승인이 필요합니다.

아키텍처 결정 사항

왜 세션 고정형인가?

상시 실행 봇은 리소스를 소비하고 오래된 컨텍스트로 동작할 수 있는 상시 실행 Claude 세션을 의미합니다. 핀 설계는 원할 때만 봇이 살아 있고, 원하지 않을 때는 꺼져 있음을 보장합니다. 이는 제한 사항이 아니라 기능입니다.

왜 두 개의 파일인가 (server.ts + proxy.ts)?

서버는 systemd 유닛으로 실행되며 Telegram 폴링 연결을 유지합니다. 프록시는 Claude가 stdio MCP 전송으로 생성합니다. 분리하면 다음과 같은 이점이 있습니다:

• 서버가 Claude와 독립적으로 재시작 가능

• 프록시가 실행 중인 서버에 재연결 가능

• Claude 세션 재시작 중에도 폴링 상태가 유실되지 않음

왜 웹훅이 아닌가?

웹훅은 공개 URL, TLS, 포트 포워딩이 필요합니다. 롱 폴링은 NAT 뒤, 노트북, VPS 어디서든 작동합니다. 머신 자체 외에 추가 인프라가 전혀 필요 없습니다.

토큰당 폴러 하나

Telegram Bot API는 두 프로세스가 동일한 토큰을 폴링하면 409 Conflict를 반환합니다. 잠금 파일(pinned.lock)이 정확히 하나의 폴러만 존재하도록 강제합니다. 세션이 정리 없이 크래시된 경우, 다음 tgpin이 오래된 PID를 감지하고 잠금을 회수합니다.

파일

라이선스

Apache-2.0 (업스트림 Claude Code Telegram 플러그인과 동일).

연락처

• GitHub: Swigler