# @framers/agentos-ext-channel-telegram 中文文档

规范地址：https://npmcn.com/package/%40framers/agentos-ext-channel-telegram/

版本：0\.1\.11
npm 元数据更新时间：2026-11-11T07:54:10.539Z
中文译文更新时间：2026-11-15T12:04:08.398Z
软件包许可：Apache-2\.0

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40framers/agentos-ext-channel-telegram
原文对照：https://npmcn.com/package/%40framers/agentos-ext-channel-telegram/?lang=original
项目主页：https://github.com/framerslab/agentos-extensions/tree/master/registry/curated/channels/telegram#readme
源码仓库：https://github.com/framerslab/agentos-extensions

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：115 kB，28 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=22
- 运行依赖：1 个
- peer 依赖：@framers/agentos \>=0\.10\.40
- 首次发布：2026-02-08T04:22:40.802Z
- 最新版本发布：2026-11-11T07:54:10.039Z
- 近 30 天下载量：21924（2026-10-16 至 2026-11-14，npm 官方下载统计）
- 已发布版本数：12（近 12 个月 12 个）

## 中文简介

AgentOS 的电报消息通道适配器 — 通过 grammY 双向消息

## 安装

```sh
npm install @framers/agentos-ext-channel-telegram
```

也可以使用：`pnpm add @framers/agentos-ext-channel-telegram`、`yarn add @framers/agentos-ext-channel-telegram`、`bun add @framers/agentos-ext-channel-telegram`

## README

# 电报频道扩展

AgentOS 的双向电报 `grammY`。 。 。 .

## 它提供什么

-   `telegramChannelSendMessage`
-   `telegramChannelSendMedia`
-   `telegramChannel`

## 运行时间状态

-   这是全程频道节目.
-   频道保持选入,因为它们可以连接,民意调查,或接收网络呼声.
-   打开它 `createCuratedManifest({ channels: ['telegram'] })` 或自定义扩展列表.

## 需要的秘密

-   `telegram.botToken`

## 业务更新

一个Telegram Business账户可以连接一个bot到它的私人聊天,然后Telegram发送那个bot `business_connection`, (中文(简体) ), `business_message`, (中文(简体) ), `edited_business_message` 财务报告和审定财务报表 `deleted_business_messages` 更新。 为了保持一个机器人不聊天, 关闭业务更新:

```ts
createExtensionPack({ options: { botToken, dropBusinessUpdates: true } });
```

或设置 `TELEGRAM_BUSINESS_UPDATES=off` 在环境中,这就使得 `dropBusinessUpdates` 默认为 `true` (明确 `dropBusinessUpdates: false` 胜过它.

商业更新关闭:

-   投票时间长 `getUpdates` a 一个 `allowed_updates` grammY 的默认更新类型列表 (`API_CONSTANTS.DEFAULT_UPDATE_TYPES`) 少了四种商业类型,并且一个webhook以相同的列表注册,因此Telegram停止提供. `chat_member`, (中文(简体) ), `message_reaction` 财务报告和审定财务报表 `message_reaction_count` 停止,因为他们是默认的.
-   一个仍然到达的业务更新,一个在列表更改前排入的Telegram队列,在任何处理器运行前被删除. 该包最多一分钟写一个警告, 与计数和种类 从更新本身.

此列表导出为 `TELEGRAM_BUSINESS_UPDATE_TYPES`,以及 `allowedUpdatesWithoutBusiness()` 返回时 `allowed_updates` 列出发件人。 该列表来自 grammY `API_CONSTANTS`,grammY从1.21.1上输出,所以包依赖于 `grammy` `^1.21.1`。 。 。 .

## 被拒绝的机器人标志

当Telegram拒绝bot 令牌(在任何Bot API 呼叫上为 401)时,适配器会发出一个 `error` 服务开始后停止投票:

```ts
adapter.on((event) => {
  if (event.data?.code === 'auth_failed') {
    // event.data is { code: 'auth_failed', channel: 'telegram' }: ask for a new token.
  }
}, ['error']);
```

-   一开始,格拉姆的第一通电话(`getMe`),或 `setWebhook` 答401:用这个错误开始拒绝.
-   在投票期间, `getUpdates` 回答401:grammY结束其投票循环.
-   在频道运行期间,任何其他呼叫回答401(发送,编辑,查询):服务停止并结束投票循环.

事件命名频道, 并带有没有符号和信件文本 。 当包激活时拒绝一个令牌, 在主机订阅前被拒绝, 所以一个订阅的处理器 `error` 事件结束后,它会得到一次, 就在它订阅之后。 服务会写一个警告. `TelegramService` 曝光情况 `tokenRejected` 财务报告和审定财务报表 `onTokenRejected(handler)`,且包输出 `CHANNEL_AUTH_FAILED_CODE` 财务报告和审定财务报表 `isTelegramTokenRejected(err)`。 。 。 .

服务器出错(500起及上行)或被丢弃的连接不是被拒绝的代号: grammY再等3 s和民调,频道持续运行.

## Bot API 服务器

包打来 `https://api.telegram.org` 除非另有说明 用一个 [本地 Bot API 服务器](https://core.telegram.org/bots/api#using-a-local-bot-api-server),或测试服务器,通过地址而不附带斜线:

```ts
createExtensionPack({ options: { botToken, apiRoot: 'http://127.0.0.1:8081' } });
```

或设置 `TELEGRAM_API_ROOT` 在环境中。 选项胜过变量 。 机器人指使符是每个请求路径的一部分,所以只指向您运行的服务器.

## 真相来源

-   `manifest.json` 定义导出的工具和消息通道描述符.
-   `src/` 包含适配器和工具执行.

## 释放

新版本发表于 [架设层/剂-外延](https://github.com/framerslab/agentos-extensions) 由 GitHub Actions 通过 npm 信任的出版, 并附有出处声明 .

## 常见问题

### @framers/agentos-ext-channel-telegram 是什么？

AgentOS 的电报消息通道适配器 — 通过 grammY 双向消息

### 如何安装 @framers/agentos-ext-channel-telegram？

在项目目录运行 npm install @framers/agentos-ext-channel-telegram，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：@framers/agentos（\>=0\.10\.40）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @framers/agentos-ext-channel-telegram 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @framers/agentos-ext-channel-telegram 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### @framers/agentos-ext-channel-telegram 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=22。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @framers/agentos-ext-channel-telegram 可以商用吗？

@framers/agentos-ext-channel-telegram 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @framers/agentos-ext-channel-telegram 的下载量有多少？

根据 npm 官方下载统计，@framers/agentos-ext-channel-telegram 在 2026/10/16 – 2026/11/14 这 30 天内被下载 21,924 次，日均约 731 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @framers/agentos-ext-channel-telegram 还在维护吗？

最新版本 0\.1\.11 发布于 2026/11/11（4 天前）；至今共发布 12 个版本，其中过去 12 个月发布了 12 个；首次发布于 2026/02/08。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。