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 路径，由根用户拥有、故障时关闭的本地重置助手支持，由 PID 1 执行。

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

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

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

快速开始

需要官方 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 替换为你自己的路径。发送一条包含 GFM 表格的消息；渲染器应报告 mode: rich。

渲染器可以独立工作。/reset 还需要根助手，需要按照 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 响应和未知结果永远不会触发重新发送。

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

完整集合见 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 且 /proc 挂载了 procfs 的 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。它从不安装根用户拥有的文件。

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

将 Telegram 凭据和允许列表保存在 Claude 的状态目录下，并将重置配置以根用户身份保存在 /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、对话记录、服务特定路径或实时重置配置。

项目状态

代码是从一个已上线、经过验证的部署中提取出来的，然后泛化成一个干净的公共仓库。API 在 1.0.0 之前可能会发生变化。

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

许可证

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

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