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 token 时发生的 409 Conflict 错误。

安全补丁

上游插件存在一个信息披露问题：/start、/help 和 /status 命令在访问门控运行之前就已注册。在 dmPolicy: "allowlist" 模式下，发现该机器人的陌生人会收到一条说明它是 Claude Code 桥接器的回复——泄露了机器人的存在及其用途。

补丁 添加了一个 commandMuted() 防护：在 allowlist 或 disabled 模式下，来自非白名单用户的命令会被静默丢弃。在配对模式下，它们正常工作（因为 /start 是新用户学习配对的方式）。

这增加了 15 行代码，无删除，可在 git diff 中查看。

设置

前置条件

• 已安装 Claude Code CLI

• Bun 运行时

• 来自 @BotFather 的 Telegram 机器人 token

1. 安装服务器

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

2. 配置机器人 token

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. 锁定访问（推荐）

默认情况下，机器人处于配对模式——任何给它发私信的人都会获得配对码。要将其锁定到你的 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 地址。免费版足够使用。

• 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 会话持续消耗资源，并可能基于过时的上下文采取行动。固定设计意味着机器人在你需要时在线，不需要时离线。这是特性，不是限制。

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

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

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

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

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

为什么不用 webhook？

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

每个 token 一个轮询器

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

文件

许可证

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

联系方式

• GitHub: Swigler