Claude Code Telegram 官方插件：完整配置指南 2026

Claude Code Telegram 官方插件：完整配置指南 2026

核心要点 (TL;DR)

  • Anthropic 官方 Claude Code Telegram 插件，让你在 Telegram 中直接与 AI 助手聊天
  • 配置仅需 6 步：创建 Bot → 安装插件 → 配置 Token → 重启 → 配对 → 锁定
  • 插件暴露三个 MCP 工具：reply（发送消息）、react（添加表情）、edit_message（编辑消息）
  • 默认访问控制为 "pairing" 模式 —— 配置完成后建议切换为 allowlist 防止陌生人访问
  • 无消息历史和搜索功能 —— Bot 只能看到实时送达的消息

目录

  1. 什么是 Claude Code Telegram 插件？
  2. 前提条件
  3. 快速配置：6 步上手
  4. 访问控制详解
  5. MCP 工具参考
  6. 图片处理
  7. 重要限制
  8. 对比：Telegram vs Discord 插件
  9. 常见问题
  10. 总结与下一步

1. 什么是 Claude Code Telegram 插件？

Claude Code Telegram 插件是 Anthropic 官方开发的 MCP（Model Context Protocol）服务器，用于将 Telegram Bot 连接到 Claude Code 会话。配置完成后，你可以通过 DM 方式向 Telegram Bot 发送消息，这些消息会被直接转发到你的 Claude Code 助手 —— 相当于通过任意 Telegram 客户端实现对 Claude Code 的移动端访问。

MCP 服务器以 Bot 身份登录 Telegram，为 Claude 提供三个工具：回复消息、添加表情反应、编辑已发送的消息。当你通过 Telegram 向 Bot 发消息时，服务器会将消息转发到你的活跃 Claude Code 会话，Claude 的回复再发送回 Telegram 聊天。

这是来自 Anthropic claude-plugins-official GitHub 仓库的官方插件，与第三方解决方案不同，这是官方推荐的 Claude Code + Telegram 集成方式。

2. 前提条件

开始之前，请确保已安装：

依赖项 详情
Bun MCP 服务器运行在 Bun 上。安装命令：curl -fsSL https://bun.sh/install \| bash
Telegram 账号 用于创建和管理 Bot
Claude Code 需先运行 claude 启动会话

专业提示 部分 MCP 服务器支持多种运行时，但官方 Telegram 插件仅支持 Bun。如果尝试使用 Node.js 或 Deno 运行，可能会遇到意外错误。

3. 快速配置：6 步上手

步骤 1：通过 BotFather 创建 Bot

在 Telegram 中打开与 @BotFather 的聊天，发送 /newbot。BotFather 会要求提供两项信息：

  1. 名称（Name） —— 聊天标题中显示的名称（可包含空格，如"Milo 的助手"）
  2. 用户名（Username） —— 以 bot 结尾的唯一句柄（如 my_claude_code_bot），这会成为 Bot 的链接：t.me/my_claude_code_bot

BotFather 会回复一个形如 123456789:AAHfiqksKZ8... 的 Token —— 需完整复制，包括开头的数字和冒号。

⚠️ 安全注意 此 Token 如同密码，请勿公开分享。任何持有者都可控制你的 Bot。

步骤 2：安装插件

这是 Claude Code 命令 —— 先运行 claude 启动会话，然后执行：

/plugin install telegram@claude-plugins-official /reload-plugins

检查 /telegram:configure 是否能 Tab 补全。若不能，请用 exit 退出会话，重新运行 claude。

步骤 3：配置 Token

/telegram:configure 123456789:AAHfiqksKZ8...

此命令将 TELEGRAM_BOT_TOKEN=... 写入 ~/.claude/channels/telegram/.env。你也可以手动编辑该文件，或在 shell 环境中设置变量 —— 若两者同时设置，shell 环境变量优先级更高。

步骤 4：通过 channel 参数重启

不带 channel 参数服务器无法连接。退出当前会话，用以下命令重新启动：

claude --channels plugin:telegram@claude-plugins-official

步骤 5：配对

  1. 在 Telegram 上向你的 Bot 发送 DM —— Bot 会回复一个 6 位数的配对码
  2. 在 Claude Code 会话中输入：
/telegram:access pair <code>

之后你的 DM 就会直接送达助手。

✅ 小贴士 与 Discord 不同，Telegram 无需服务器邀请步骤 —— Bot 可以直接接收 DM。配对机制负责用户 ID 查找，无需接触数值 ID。

步骤 6：锁定配置

配对仅用于获取 ID。配对完成后，切换到 allowlist 模式，防止陌生人获取配对码。可以通过 Claude 助手完成，也可以直接运行：

/telegram:access policy allowlist

4. 访问控制详解

插件支持多种访问策略。DM 策略、群组、提及检测、投递配置、技能命令及 access.json 架构详见仓库中的 ACCESS.md。

快速参考： - ID 为数值用户 ID（可从 @userinfobot 获取） - 默认策略为 pairing - ackReaction 仅接受 Telegram 的固定表情白名单（ ❤ 等）

策略 行为
pairing 用户需完成 6 位配对码流程（默认）
allowlist 仅预批准的用户 ID 可与 Bot 交互
open 任何人都可向 Bot 发消息（不推荐）

5. MCP 工具参考

插件向助手暴露了三个工具：

工具 功能
reply 向聊天发送消息。接收 chat_id + text，可选 reply_to（消息 ID，用于原生线程）和 files（绝对路径，用于附件）。图片（.jpg/.png/.gif/.webp）以照片形式发送并带内联预览；其他类型作为文件发送。每文件最大 50MB。长文本自动分块；文件在文本消息后单独发送。返回发送的消息 ID。
react 按消息 ID 添加表情反应。仅接受 Telegram 固定表情白名单（ ❤ 等）
edit_message 编辑 Bot 之前发送的消息。适合"处理中…" → "已完成"的进度更新场景。仅能编辑 Bot 自己的消息。

关于收到的消息： 收到消息时会自动触发打字指示器 —— Telegram 会显示"Bot 名称正在输入…"，直到助手响应。

6. 图片处理

向 Bot 发送图片时： - 收到的图片会下载到 ~/.claude/channels/telegram/inbox/ - 本地路径会包含在 <channel> 通知中，助手可使用 Read 工具处理 - Telegram 会对图片进行压缩 —— 如需原始文件，请以文档方式发送（长按 → 发送为文件）

7. 重要限制

无历史记录和搜索

Telegram Bot API 既不提供消息历史，也不提供搜索功能。Bot 只能看到实时到达的消息，不存在 fetch_messages 工具。如果助手需要早期上下文，它会要求你粘贴或总结。

这也意味着无法获取历史消息的附件 —— 由于无法事后获取，图片在到达时就会立即下载。

无法主动拉取消息

与 Discord 不同，Telegram Bot 无法主动拉取消息。Bot 完全在推送模式下运行 —— 接收消息并响应，但不能翻回去读取聊天中的旧消息。

8. 对比：Telegram vs Discord 插件

功能 Telegram 插件 Discord 插件
配置复杂度 更简单 —— 无需服务器邀请 步骤更多 —— 需要服务器邀请
访问控制 数值用户 ID Discord 角色/雪花 ID
消息历史 不可用 不可用
打字指示器 自动 自动
文件支持 图片 + 文档，最大 50MB 依 Discord 限制而定
线程化 通过 reply_to 消息 ID Discord 原生线程
配对流程 DM 发送 6 位码 基于服务器的邀请

对于单用户场景，Telegram 插件通常更简单 —— 无需服务器邀请，直接 DM Bot 即可。

9. 常见问题

Q：支持多用户吗？

支持，但需要通过 access.json 策略系统配置多用户访问。默认的 pairing 策略允许新用户自行配对，allowlist 模式则需要预先审批。

Q：为什么无法搜索旧消息？

Telegram Bot API 不提供消息历史访问权限。Bot 仅能接收运行期间到达的消息。建议对重要对话做好总结存档。

Q：支持群聊吗？

支持，详见 ACCESS.md 中的群组、提及检测和群组特定配置。建议配置提及检测，让 Bot 仅在被明确 @ 时响应。

Q：图片模糊怎么办？

Telegram 会对作为图片发送的照片进行压缩。如需原始质量，请以文档方式发送（长按 → 发送为文件）。

Q：Bot 离线时发消息会怎样？

离线期间发送的消息会丢失 —— 不支持消息队列。未收到回复的消息需要重新发送。

10. 总结与下一步

官方 Claude Code Telegram 插件是将 AI 助手接入 Telegram 的推荐方案。只需六步即可获得：

  • 任意 Telegram 客户端直接访问 Claude Code
  • 三个强大的 MCP 工具（回复、反应、编辑）
  • 灵活的访问控制策略
  • 自动打字指示器
  • 带本地下载功能的图片处理

下一步： 1. 在 @BotFather 创建你的 Bot 2. 通过 /plugin install telegram@claude-plugins-official 安装插件 3. 配置 Token 并以 channel 参数重启 4. 完成 Telegram 账号配对 5. 切换到 allowlist 策略加固安全

高级配置（群组、提及检测、技能命令）请参阅官方仓库中的完整 ACCESS.md。

文章来源： Anthropic 官方 Claude Code Telegram 插件 README

posted on 2026-03-20 08:33  见路非道  阅读(311)  评论(0)    收藏  举报