AGENTSPACE
图 文 · 转 载

Telegram 的 AI 自动化生态,小白从零看懂机器人、MCP、Skills 到底怎么接

作者 @wlzh(M.) 发布于 2026-11-19 约 7650 字 · 阅读约 19 分钟 查看原文 ↗

想让 AI 帮忙盯 Telegram、回消息、总结群聊,到底该装哪个。

说实话,这个问题没法一句话回答。Telegram 上的 AI 自动化现在是一整套东西,机器人、用户号、MCP、Skills、各种 Agent 网关,名字一堆,新手一上来就容易装错。

读完这篇,你能分清这几件事。两条接入路线差在哪,MCP 和 Skills 各管什么,Claude Code、Codex、Cursor、OpenClaw、Hermes、n8n 分别怎么接,还有哪些坑会让你丢号。

一、先分清两条路,后面所有选择都从这里分叉

Telegram 给程序留了两个入口。

第一条是机器人,走 Bot API。你找 @BotFather 建一个机器人,拿到一串 token,程序拿着 token 收发消息。机器人不需要手机号。

第二条是用户号,走 MTProto。程序登录的是你自己的真人账号,要去 my.telegram.org 申请 api_id 和 api_hash,再用手机号登录一次生成会话。

这两条路能做的事差很多,我把官方写明的几条限制放在一起看。

机器人不能先开口。官方原文是 “Bots can't start conversations with users. A user must either add them to a group or send them a message first.”

机器人读不了历史消息,也不能搜索。Claude Code 官方 Telegram 插件的 README 写得很直白:“Telegram's Bot API exposes neither message history nor search.”

用户号这边,你的账号在群里能看到的,程序都能看到,历史也能读。代价是风险。Telegram 官方在申请 api_id 的页面写着,所有用非官方客户端登录的账号都会被自动放进观察名单,滥用会被永久封禁。

下面这张图把两条路的差别画在了一起。

左边是机器人路线,右边是用户号路线。

我的选择是,小白先走机器人这条路。只有确实要读历史、总结未读的时候,再考虑用户号,而且只开只读权限。

二、整个生态长什么样

名字多,其实就四层。

最底下是 Telegram 的两个入口,上一节讲过了。

往上一层是开发库。机器人这边常见的有 python-telegram-bot、aiogram、grammY、telegraf。用户号这边有 Telegram 官方的 TDLib,还有 kurigram、mtcute。

这里有个容易被老教程带偏的地方。老教程最爱推荐的 Telethon、gramjs、pyrogram,这三个 GitHub 仓库现在都已经是归档状态。Telethon 的 README 第一行写着仓库已搬到 Codeberg。照着两三年前的教程装,装到的可能是没人维护的版本。

再往上是给 AI 用的接口层,也就是 MCP 服务器和 Skills。

最上面是各种 Agent,Claude Code、Codex、Cursor、OpenClaw、Hermes、n8n 都在这一层。

从下到上是入口、开发库、MCP 与 Skills、各种 Agent。

小白不用自己写代码调开发库。你要做的是选一个 Agent,再决定它通过哪种方式碰到 Telegram。

三、第一步,找 BotFather 建一个机器人

后面大部分方案都要先有一个机器人,所以这步先做。

下面这张是 Telegram 官方文档里讲建机器人的那一页。看图里的步骤说明,重点是 /newbot 这个命令和 username 的规则。

按官方文档,步骤是这样的。

  1. 在 Telegram 里搜 @BotFather,给它发 /newbot
  2. 它会问两样东西,一个是显示名,一个是 username
  3. username 长度 5 到 32 个字符,只能用拉丁字母、数字和下划线,必须以 bot 结尾,建好以后不能改
  4. 建完它会给你一串 token,官方给的样例是 110201543:AAHdqTcvCH1vGWJxfSeofSAs0K5PALDsaw

注意点有三个。

第一,认准本尊。OpenClaw 的文档专门提醒要确认用户名一字不差就是 @BotFather。下面这张是 BotFather 的公开主页,看用户名和蓝色认证标记。

第二,token 就是这个机器人的全部控制权。官方原文是 “Everyone who has your token will have full control over your bot.” 不要贴进聊天,不要截图发群,不要提交到 git。泄露了就回 BotFather 发 /token 重新生成。

第三,username 定了不能改,起名之前想一想。

四、第二步,把 Agent 接进 Telegram

有了机器人,接下来是让 AI 住进去。我按上手难度排了四个。

1. Claude Code 官方 Telegram 插件

这是 Anthropic 官方仓库 anthropics/claude-plugins-official 里的插件,README 第一句是 “Connect a Telegram bot to your Claude Code with an MCP server.”

下面这张是插件的 README 页面,看 Quick Setup 里的安装命令和前几步。

前置是先装 Bun,README 给的命令是

bash
curl -fsSL https://bun.sh/install | bash

然后按 Claude Code 官方文档的五步走。

第一步是上一节的 /newbot。

第二步,在 Claude Code 里安装插件。

/plugin install telegram@claude-plugins-official

第三步,把 token 交给插件。README 里的示例长这样,后面那串是占位符,换成你自己的。

/telegram:configure 123456789:AAHfiqksKZ8...

官方文档说 token 会存到 ~/.claude/channels/telegram/.env。

第四步,带频道参数重启。

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

第五步,在 Telegram 里给机器人发条消息,拿到配对码,回到 Claude Code 输入

/telegram:access pair <code>

配完别停,再补一条。

/telegram:access policy allowlist

这一条不能省。README 的原话是配对完就切到 allowlist,免得陌生人也收到配对码回复。官方文档还有一句更重的:“Anyone who can reply through the channel can approve or deny tool use in your session”。能在这个频道里说话的人,就能替你批准 AI 在你电脑上动手。

还有两个限制要先知道。这个功能目前是 research preview。消息只在 Claude Code 会话开着的时候才送得到,关了终端机器人就不理人了。

2. OpenClaw

想要 7×24 在线,得用常驻的网关。openclaw/openclaw 是其中一个,MIT 许可证,star 数 39 万多。

下面这张是它的仓库主页。

README 给的安装命令,macOS、Linux 和 WSL2 是

bash
curl -fsSL https://openclaw.ai/install.sh | bash

装完跑引导。

bash
openclaw onboard --install-daemon

接 Telegram,文档原文是一条命令。

bash
openclaw channels add --channel telegram --token <bot-token>

然后检查状态。

bash
openclaw channels status --probe

OpenClaw 默认陌生人私聊要先配对,文档写配对码一小时过期。批准配对用这两条。

bash
openclaw pairing list telegram
openclaw pairing approve telegram <CODE>

这里要提醒一句,curl ... | bash 这种安装方式是把网上的脚本直接交给你的电脑执行。稳妥的做法是,跑之前先打开那个地址看一眼脚本内容,确认域名没拼错。

3. Hermes Agent

NousResearch/hermes-agent,MIT 许可证,一个网关进程同时接 Telegram、Discord、Slack。

安装命令,README 原文。

bash
curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash

接 Telegram 走向导。

bash
hermes gateway setup

想手动配的话,文档说写到 ~/.hermes/.env,一行填机器人 token,变量名是 TELEGRAM_BOT_TOKEN,另一行限定谁能用,原文是

bash
TELEGRAM_ALLOWED_USERS=123456789 # Comma-separated for multiple users

然后启动。

bash
hermes gateway

注意这里填的是数字用户 ID,不是用户名。好几份文档都让你去找 @userinfobot 查自己的 ID。

4. cc-connect

chenhg5/cc-connect 的定位是把你电脑上已有的编程 Agent 桥接到聊天平台,README 列的是 Claude Code、Cursor、Gemini CLI、Codex。

bash
npm install -g cc-connect

它的文档有一点对小白很友好,写明用的是 Long Polling 模式,不用公网 IP,不用域名,也不用反向代理。

但有个默认值要盯住。配置里的 allow_from 不填的时候,文档写的是所有用户都被允许,只会打一条警告日志。装完第一件事就是把它填成你自己的数字 ID。

五、MCP 是什么,怎么把 Telegram 接给 AI

MCP 官方的定义是 “an open-source standard for connecting AI applications to external systems”。官方页面拿 USB-C 打比方,我觉得这个比方够用了。AI 是电脑,MCP 是那个统一的插口,Telegram 是插上去的设备。

Agent 通过 MCP 服务器调用 Telegram 的工具。

Telegram 方向的 MCP 服务器,我挑了三个还在更新的。

后两个走的是用户号,意思是 AI 拿到的是你真人账号的权限。装之前先把这句话读三遍。

先说一个真实存在的大坑

下面这张是 chigwell/telegram-mcp 的 README,看那段警告。

README 的原文是

Do not install this server with uvx telegram-mcp, uvx --from telegram-mcp, or pip install telegram-mcp. The telegram-mcp name on PyPI is currently owned by a different project and does not install this repository.

翻成大白话,PyPI 上叫 telegram-mcp 的那个包是别人的项目。你照着某些教程敲 uvx telegram-mcp,再把 api_id、api_hash 和会话字符串喂给它,账号凭证就交到了不相干的代码手里。

正确装法照 README 来。

bash
git clone https://github.com/chigwell/telegram-mcp.git
cd telegram-mcp
uv sync

生成会话字符串。README 写的是,另一台设备上已经开着 Telegram 的话,推荐扫码登录。

bash
uv run session_string_generator.py --qr

然后把三个值填进环境变量。

env
TELEGRAM_API_ID=your_api_id_here
TELEGRAM_API_HASH=your_api_hash_here
TELEGRAM_SESSION_STRING=your_session_string_here

api_id 和 api_hash 去 my.telegram.org 申请,登录后进 “API development tools” 填表。官方页面写明一个手机号目前只能绑一个 api_id。

下面这张是 my.telegram.org 的登录页,认准域名。这个页面只会要你的手机号和 Telegram 发来的确认码。

在各个 Agent 里登记 MCP 服务器

写法各家不同,位置按各家官方文档是这样的。

Claude Code 用命令加,-- 后面跟启动命令。官方文档的示例是

claude mcp add playwright -- npx -y @playwright/mcp@latest

项目级配置存在项目根目录的 .mcp.json,个人级存在 ~/.claude.json。

Cursor 用 JSON 文件,项目级是 .cursor/mcp.json,全局是 ~/.cursor/mcp.json。chaindead 的 README 给了一份 Cursor 配置。

json
{
  "mcpServers": {
    "telegram": {
      "command": "npx",
      "args": ["-y", "@chaindead/telegram-mcp"],
      "env": {
        "TG_APP_ID": "<your-api-id>",
        "TG_API_HASH": "<your-api-hash>"
      }
    }
  }
}

这份配置里有 api_id 和 api_hash。Cursor 官方的要求是 “Use environment variables for secrets, never hardcode them”,而项目级的 .cursor/mcp.json 官方又建议提交到 git 给队友共用。所以带凭证的配置放全局那份,别进仓库。

Codex 用 TOML,官方文档说默认是 ~/.codex/config.toml,每个服务器一张 [mcp_servers.<server-name>] 表。官方示例是

toml
[mcp_servers.context7]
command = "npx"
args = ["-y", "@upstash/context7-mcp"]

Hermes 写在 ~/.hermes/config.yaml 的 mcp_servers 下面,文档说 MCP 支持随标准安装自带。

chigwell 的 README 还给了一种共享 HTTP 服务器的接法,Claude Code 和 Codex 各一条命令。

bash
# Claude Code
claude mcp add --transport http telegram http://127.0.0.1:8765/mcp

# Codex
codex mcp add telegram --url http://127.0.0.1:8765/mcp

先只读,再考虑放权

chigwell 提供了一个开关,在 env 里加一行,AI 就只能读不能发。

json
"TELEGRAM_EXPOSED_TOOLS": "read-only"

我的建议是所有用户号方案都从只读开始。让 AI 总结未读、帮你起草回复,这些只读就够了。发送这个动作留给你自己点。

六、Skills 是什么,和 MCP 差在哪

Skills 的官方说明很短:“a skill is a folder containing a SKILL.md file”。一个技能就是一个文件夹,里面一份 SKILL.md,写着名字、描述和操作说明。

下面这张是 Agent Skills 规范的官网首页。

官网写它最初由 Anthropic 开发,后来作为开放标准放出来。

它的加载方式分三段。启动时 Agent 只读每个技能的名字和描述。任务对上了某个描述,才把整份 SKILL.md 读进来。执行时再按需跑里面带的脚本。

最小的一份 SKILL.md 长这样,这是规范给的原文。

markdown
---
name: skill-name
description: A description of what this skill does and when to use it.
---

MCP 和 Skills 的分工,我是这么理解的。MCP 给 AI 一双能伸到 Telegram 里的手,Skills 是告诉它这双手该怎么用的说明书。两样经常搭着用,chigwell 的仓库里就自带一个 skills 目录,教 AI 怎么安全地总结未读、怎么只起草不发送。

发现、激活、执行三步。

一个现成的 Telegram 技能

paul-nameless/tg 是个终端里的 Telegram 客户端,走用户号,自带一个给 Agent 用的技能。

sh
pip3 install tg
tg skill install

README 说 tg skill install 会把技能文件复制到 ~/.claude/skills/tg/SKILL.md(Claude Code)和 ~/.agents/skills/tg/SKILL.md(Codex、opencode)。

它的默认设置我很喜欢。README 写着读消息不会把消息标成已读,发送默认关闭,要自己去 conf.py 里打开。

各个 Agent 把技能放哪

七、不想碰命令行,还有 n8n

n8n 是拖拽式的工作流平台。它的许可证不是标准开源许可证,README 写的是 Sustainable Use License,商用前自己看条款。

n8n 的 Telegram 节点只支持一种认证,就是机器人 token。在 BotFather 建好机器人,把 token 填到 n8n 凭证的 Access Token 里就行。

它和 MCP 的关系是双向的。有个节点叫 MCP Client Tool,让 n8n 里的 AI Agent 去用外部 MCP 服务器的工具。还有个节点叫 MCP Server Trigger,让 n8n 自己当 MCP 服务器,把工作流开放给别的 Agent 调。官方文档写后者目前不支持 stdio 传输。

八、小白最容易踩的坑,我按严重程度排了一下

六条最要紧的坑。

会丢号、丢控制权的

会让你以为“坏了”的

规则红线

Telegram 的 API 服务条款明确禁止用平台数据训练或微调 AI 模型,机器人开发者条款也禁止为了建数据集去采集群和频道内容。让 AI 总结你自己的未读,和批量抓公开群做数据集,是两回事。

容易被忽略的

聊天内容里可能藏着写给 AI 的指令。chigwell 的 README 把消息、显示名、群标题、按钮文字都列为不可信内容。这也是前面建议先只读的原因,AI 被一条消息带偏的时候,至少它发不出东西。

九、如果从头来,我会按这个顺序

第一步,建机器人,只做 BotFather 那一节。

第二步,装 Claude Code 官方插件,体验在 Telegram 里跟自己电脑上的 AI 说话。配对完立刻切 allowlist。

第三步,想让它一直在线,再换 OpenClaw、Hermes 或 cc-connect 这类常驻网关,白名单先填好。

第四步,确实需要读历史、总结未读,再上用户号的 MCP,全程只读起步。

第五步,把常用的操作写成 Skills,让 AI 每次都按同一套规矩做。

这个顺序的逻辑很简单,权限从小往大放。机器人出事,损失的是一个可以重置的 token。用户号出事,损失的是你用了很多年的账号。