Claude Code ↔ Telegram Bridge

面向 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
└─────────────────────┘

固定（pin）设计： 同一时间只有一个 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 会自动启动和停止它。启用它会使机器人常驻，与固定（pin）设计相冲突。

4. 安装启动器

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

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

5. 锁定访问（推荐）

默认情况下，机器人处于配对模式——任何私信它的人都会获得配对码。要将其锁定到你的 Telegram 用户 ID：

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

在 Telegram 上向 @userinfobot 发送消息即可找到你的用户 ID。

使用方法

启动会话

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 模式运行，因此破坏性操作（文件写入、shell 命令）在执行前需要你明确点击确认。

架构决策

为什么采用会话固定？

常驻机器人意味着常驻的 Claude 会话会消耗资源，并可能基于过时的上下文执行操作。固定（pin）设计意味着机器人在你需要时在线，不需要时离线。这是一个特性，而非限制。

为什么用两个文件（server.ts + proxy.ts）？

服务器以 systemd 单元形式运行，持有 Telegram 轮询连接。代理由 Claude 作为 stdio MCP 传输层生成。将它们分离意味着：

• 服务器可以独立于 Claude 重启

• 代理可以重新连接到正在运行的服务器

• Claude 会话重启期间不会丢失轮询状态

为什么不用 webhook？

Webhook 需要公网 URL、TLS 和端口转发。长轮询在任何地方都能工作——NAT 后面、笔记本电脑上、VPS 上。除了机器本身，零基础设施需求。

每个令牌一个轮询器

如果两个进程轮询同一个令牌，Telegram 的 Bot API 会返回 409 Conflict。锁文件（pinned.lock）强制只允许一个轮询器。如果会话崩溃且未清理，下一个 tgpin 会检测到过期的 PID 并重新获取锁。

文件

许可证

Apache-2.0（与上游 Claude Code Telegram 插件相同）。

联系方式

• GitHub: Swigler