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를 방지합니다.

Related MCP server: tsgram-mcp

보안 패치

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

패치는 commandMuted() 가드를 추가합니다. allowlist 또는 disabled 모드에서는 허용 목록에 없는 사용자의 명령이 조용히 무시됩니다. 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 주소를 지원합니다. Starter 요금제로 충분합니다.

• 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