Claude Code Telegram Kit

不是又一个 Telegram 桥接器。 Anthropic 官方的 Claude Code Channel 只处理入站消息。这个工具包修复了它做不到的两件事：能在 Telegram 解析器中存活下来的 Markdown，以及从手机上重置上下文。

研究预览版基础设施。在将其连接到存有有价值数据的机器之前，请先审查安全模型。

同一份 Markdown 文档，两条路径。官方的 reply 工具默认使用 format: "text"，因此标记会原样呈现；其 markdownv2 模式将 MarkdownV2 转义工作推给了模型，只要漏掉一个字符就会导致发送失败。send_reply 接收未转义的文档，并自行选择传输方式。（图片来自两条路径的渲染结果，并非设备截图。）

为什么需要这个

其他每一个 "Claude Code + Telegram" 项目都替换了官方的 Channel：有自己的轮询器、自己的会话管理、自己的配对方式。这个项目不这样做。入站轮询、发送者配对、附件和权限转发都保留在 Anthropic 的插件中。本工具包在其旁边增加了两个有界的出站/控制能力，且没有引入第二个 getUpdates 消费者：

• Telegram Renderer MCP — 一个规范的 send_reply(raw Markdown) 工具，具有确定性的富消息与 MarkdownV2 路由选择、仅限永久的回退机制，以及 👀 → 👍/👎 处理反应。

• Session Control MCP — 一个需要审批的 /reset 路径，先完成已确认的接受反应，然后将执行权交给一个由 root 拥有、故障时关闭的本地重置辅助程序，由 PID 1 执行。

这两个缺口在上游都是已知的。本工具包是临时的解决方案：

• anthropics/claude-code#39684 — 无法远程清除或重置上下文

• anthropics/claude-code#36622 和 claude-plugins-official#774 — 请求支持 MarkdownV2 parse_mode

Related MCP server: tsgram-mcp

快速开始

需要官方的 telegram@claude-plugins-official 插件已经配对并正常工作。

git clone https://github.com/project-tharsis/claude-code-telegram-kit
cd claude-code-telegram-kit
bun install --frozen-lockfile
bun run check

sha=$(git rev-parse HEAD)
python3 scripts/deploy_local.py install --repo . --ref "$sha" --bun "$(command -v bun)"

然后将 examples/.mcp.json、examples/telegram-settings.json 和 examples/CLAUDE.md 复制到你的 Claude 项目中，将 USER 替换为你自己的路径。将 examples/access-ux.json 合并到官方 Channel 的 access.json 中，以启用初始的 👀 确认。发送一条包含 GFM 表格的消息；渲染器应报告 mode: rich 并将 👀 替换为 👍。

渲染器可以独立工作。/reset 还需要 root 辅助程序，请按照 session-control README 中的精确提交过程单独安装。

对于生产部署、回滚和验证，请遵循运维手册，而不是本节内容。

架构

Telegram
  -> telegram@claude-plugins-official     # sole inbound poller
  -> Claude Code
     -> telegram-renderer MCP              # bounded outbound rendering
     -> session-control MCP                # bounded reset scheduling
        -> systemd transient unit
        -> root-owned session reset helper

渲染器和控制 MCP 复用官方 Channel 的令牌和 access.json 权限。它们要求 dmPolicy: allowlist、安全的 0600 状态文件以及精确的目标成员身份。

设计不变量

以下五点定义了影响范围：

• 每个机器人令牌只有一个 Telegram getUpdates 消费者。

• 没有任意的 Bot API 方法工具。

• 没有任意的 shell 命令工具。

• 超时、429 错误、5xx 响应和未知结果永远不会触发重新发送。

• 在 Claude 进程被终止之前，PID 1 拥有重置执行权。

完整列表见 docs/design-invariants.md。

仓库布局

packages/
  shared/                  Telegram authority validation
  telegram-renderer-mcp/   Markdown renderer and MCP server
  session-control-mcp/     Reset controller, MCP server, root helper
examples/                  Generic Claude, MCP, systemd, and reset config
scripts/                   Versioned local install and rollback

要求

• 安装了 systemd 且 procfs 挂载在 /proc 的 Linux 系统

• Claude Code 2.1.234 或更新版本

• Bun 1.3.14 或更新版本

• Python 3.11 或更新版本

• Anthropic 官方的 telegram@claude-plugins-official 插件

安装模型

不要从可变的开发检出中运行生产环境。将精确的提交安装到版本化的发布目录中：

~/.local/share/claude-code-telegram-kit/
  releases/<git-sha>/
  current -> releases/<git-sha>
  previous -> releases/<previous-sha>

scripts/deploy_local.py 使用兼容 Python 3.11 的无链接/无遍历提取器提取 Git 归档，安装生产依赖项，验证发布收据，并原子性地交换 current/previous。它从不安装 root 拥有的文件。

python3 scripts/deploy_local.py status
python3 scripts/deploy_local.py rollback

将 Telegram 凭据和允许列表保存在 Claude 的状态目录下，并将重置配置以 root 身份保存在 /etc/claude-code-telegram-kit/ 下。

会话重置

本地恢复权限是：

sudo claude-code-session-reset --config /etc/claude-code-telegram-kit/reset.json

可选的 Telegram /reset 命令是一个轻量级的 MCP 前端。它无法恢复一个已经无法接收消息的 Claude 进程；请保留本地辅助程序作为紧急备用路径。

开发

bun install --frozen-lockfile
bun run check
bun audit

安全性

在部署之前请阅读 SECURITY.md。切勿提交机器人令牌、聊天 ID、对话记录、服务特定路径或实时重置配置。

项目状态

代码从一个正在运行、经过验证的部署中提取出来，然后泛化成一个隔离的公共仓库。在 1.0.0 版本之前，API 可能会发生变化。

初始版本仅提供源代码。工作区包标记为 private，不会发布到 npm；请使用版本化部署脚本从精确的 Git 提交安装。

许可证

Apache-2.0。请参阅 LICENSE、NOTICE 和 THIRD_PARTY_NOTICES.md。发布流程：RELEASING.md。

本项目是独立的，未经 Anthropic 或 Telegram 认可。