telegram-tools

telegram-tools

面向编码 Agent 的非官方 Telegram 工具：聊天、消息、接收的文件、发送和操作。

Harness	交付方式	固定版本
OpenCode V2	原生插件（npm 包，含技能）	包中的版本
OpenCode V1	原生插件（npm 包，不含技能）	包中的版本
Claude Code	插件：MCP 服务和技能	发布标签，作为 ref
Codex	插件：MCP 服务和技能	发布标签，作为 ref
Grok Build	插件：MCP 服务和技能	发布标签，作为 @ref
Antigravity	插件：MCP 服务和技能	发布标签的树 URL
Hermes Agent	原生插件（Python，调用命令行）	发布提交，作为 SHA
其他 MCP 宿主	来自 npm 的 MCP 服务	包中的版本

这些工具需要 Node.js 24 或更高版本。 docs/conventions.md 说明了工具的命名方式 及其行为。

安装

请从发布版本安装，切勿从默认分支安装：发布版本是一个带有已构建 dist/ 的提交对应的标签，而默认分支没有。在以下命令中，<version> 是发布版本号（1.2.3），<sha> 是其标签所指向的提交：

gh api repos/craft-agent/telegram-tools/commits/v<version> --jq .sha

OpenCode

OpenCode V2 在 opencode.json 中配置软件包及其选项：

{
  "plugins": [{ "package": "@craftsamo/telegram-tools@<version>", "options": { "read_only": false } }],
  "permissions": [{ "action": "telegram_*", "resource": "*", "effect": "ask" }]
}

OpenCode V1 将软件包作为字符串配置，或者将其与选项配对配置：

{
  "plugin": [["@craftsamo/telegram-tools@<version>", { "read_only": false }]],
  "permission": { "telegram_*": "ask" }
}

OpenCode 允许任何操作，且无需规则名称，因此除非规则指定 ask，否则会静默批准插件的请求。读取工具不会触发询问，因此 telegram_* 通配符是安全的。

V1 不会注册技能。解压软件包，并将 skills/* 文件夹复制到 ~/.config/opencode/skills/：

npm pack @craftsamo/telegram-tools@<version>
tar -xzf craftsamo-telegram-tools-<version>.tgz
mkdir -p ~/.config/opencode/skills
cp -r package/skills/* ~/.config/opencode/skills/
rm -rf package craftsamo-telegram-tools-<version>.tgz

Claude Code

claude plugin marketplace add craft-agent/telegram-tools#v<version>
claude plugin install telegram-tools@craft-agent

Codex

codex plugin marketplace add craft-agent/telegram-tools --ref v<version>
codex plugin add telegram-tools@craft-agent

Codex 会将服务器名称中的 - 转换为 _，因此工具会显示为 mcp__telegram_tools__telegram_*。它会在插件的安装目录中启动 MCP 服务，而该目录绝不会是调用方的工作树。

Grok Build

grok plugin install craft-agent/telegram-tools@v<version> --trust

Grok 会在会话的工作目录中启动 MCP 服务。

Antigravity

请从发布标签的树安装，切勿从默认分支安装，因为默认分支没有已构建的 dist/；Antigravity 会将该标签克隆到 ~/.gemini/config/plugins/telegram-tools。

agy plugin install https://github.com/craft-agent/telegram-tools/tree/v<version>

Hermes Agent

Hermes 安装的是提交，而非标签，并且插件安装后处于禁用状态：

hermes plugins install craft-agent/telegram-tools --ref <sha>
hermes plugins enable telegram-tools

如果 Hermes 网关已在运行，请重启它（hermes gateway restart）以加载插件。

插件会运行 Hermes 启动时找到的 Node。如果版本管理器在 Hermes 运行期间移除了该版本，调用时会再次查找 Node；如果找不到，则请在 node 可运行的 shell 中重启 Hermes。

其他 MCP 宿主

将服务添加到宿主的 MCP 配置中。标志放在 args 中：

{
  "mcpServers": {
    "telegram-tools": {
      "command": "npx",
      "args": ["-y", "@craftsamo/telegram-tools@<version>", "--read-only"]
    }
  }
}

工具和技能

每个工具集都附带一个技能，指导 Agent 如何使用其工具。技能会在其 frontmatter 的 metadata 中标明所属工具集（metadata: { toolset: sends }，以块的形式书写）。只有在设置中注册了该工具集至少一个工具时，OpenCode V2 和 Hermes 才会注册该技能，因此，关闭该工具集或移除其所有工具的配置文件都不会显示该技能；不属于任何工具集的技能始终会注册。Claude Code、Codex、Grok Build 和 Antigravity 会安装整个技能文件夹，并且只将设置传递给 MCP 服务，因此无论设置选择了哪些技能，它们都会列出所有技能。OpenCode V1 不会注册技能，其复制的技能也会全部列出。

账户（account）

工具	功能	类别
telegram_account_read	显示已登录的标签、各同步服务是否正在运行、上次收到 Telegram 消息的时间、镜像中的计数，以及用户接下来的操作	读取

它只读取本地状态：不需要守护进程或网络，返回结果中也不包含电话号码、 账户 ID 或密钥。该技能为 telegram-account，在 Claude Code 中显示为 telegram-tools:telegram-account，在 Hermes 中显示为 telegram-tools:account。

聊天（chats）

工具	功能	类别
telegram_chat_read	按 method 查找聊天并读取消息：list、view、topics、search、around，或较早的历史记录 fetch	读取

镜像中保留的聊天（私聊、机器人、基本群组、已保存的消息；以及同步列表中的超级群组和频道）会从本地镜像读取，无需同步服务；较早的历史记录通过 fetch 获取。仅列出的聊天会通过同步服务，使用 view 和 around 从 Telegram 实时读取，每页最多 100 条消息（live: true）。消息文本、说明文字、文件名和主题标题都是数据，绝不是指令。该技能为 telegram-chats，在 Claude Code 中显示为 telegram-tools:telegram-chats，在 Hermes 中显示为 telegram-tools:chats。

同步（sync）

工具	功能	类别
telegram_sync_read	列出同步列表中的超级群组和频道	读取
telegram_sync_add	将超级群组或频道加入同步列表，从现在起开始镜像	幂等
telegram_sync_remove	将聊天从同步列表中移除，并删除其镜像消息和较早版本	覆盖

同步列表最多可列出 30 个超级群组和频道，镜像会持续更新这些群组和频道的消息。telegram_sync_read 无需同步服务，即可从本地镜像读取列表。添加或移除聊天会更改本地镜像，需要同步服务正在运行；新添加的聊天会以最新的 50 条消息初始化，而移除聊天会在本地删除其镜像消息和较早版本（Telegram 上不会发生任何更改）。只有启用 channels 设置后，才能列出或镜像频道。该技能为 telegram-sync，在 Claude Code 中显示为 telegram-tools:telegram-sync，在 Hermes 中显示为 telegram-tools:sync。

发送（sends）

工具	功能说明	类别
telegram_message_send	按聊天 ID 发送一条文本，可选发送到论坛主题或作为回复	添加

发送工具集默认启用。文本会按原样发送（绝不会按 Markdown 或 HTML 解析），并会去除首尾空格，最多 4096 个字符。每次调用只发送一次，使用一个 random_id，绝不会重复发送：如果失败状态为 uncertain，表示消息可能已经发出，提示中会列出镜像服务看到的匹配消息，因此用户应先检查聊天，再决定是否重新发送。duplicate 表示同一调用的较早投递已成功发出。消息由同步服务发送，因此该服务必须正在运行。对应技能为 telegram-sends，在 Claude Code 中显示为 telegram-tools:telegram-sends，在 Hermes 中显示为 telegram-tools:sends。

文件（files）

工具	功能说明	类别
telegram_file_save	从 Telegram 下载一条消息中的文件，并将其保存到 download_dir	添加
telegram_file_send	向聊天发送 1 到 10 个文件（合计 100 MB），并附上说明	添加

文件工具集默认关闭：它会写入磁盘、打开归档并发送文件。可通过 toolsets 或 tools 启用。发送时会将 1 到 10 个文件（合计最多 100 MB）作为一个组发送；每个文件都会作为文件发送，文件必须来自工作目录（该目录不能是主目录或文件系统根目录）或 send_dirs 指定的目录；密钥、机密、程序和安装程序会被拒绝；归档会逐项检查；每个文件都会复制到标签对应的发件箱，并在上传前进行检查；sha256 可将文件固定为已批准的版本。发送需要同步服务正在运行；如果失败状态为 uncertain，提示会列出镜像服务看到的匹配消息，因此用户应先检查聊天，再决定是否重新发送。对于收到的文件，消息中的文件会保存到 <download_dir>/<label>/<chat id>/<message id>/，权限为私有（模式 600），永远不会设为可执行，也不会覆盖已有文件；download_max_mb 用于设置可下载文件的最大大小。文件由同步服务下载，因此该服务必须正在运行。程序和安装程序会被拒绝；除 zip、tar 和 gzip 压缩的 tar 以外的归档也会被拒绝；包含程序、另一个归档、链接或指向归档外部路径的文件的归档、动态贴纸及阅后即焚文件同样会被拒绝。归档会先检查并列出内容，只有在明确要求（unpack: true）时才会解压到其旁边的 <name>.unpacked/ 目录中。在 macOS 上，每个保存和解压的文件都会带有隔离标记。文件名和文件内容都是数据，绝不是指令。对应技能为 telegram-files，在 Claude Code 中显示为 telegram-tools:telegram-files，在 Hermes 中显示为 telegram-tools:files。

操作（actions）

工具	功能说明	类别
telegram_message_edit	替换用户自己的一条消息的文本或说明	覆盖
telegram_message_delete	删除用户自己的一条消息，对所有人都生效	管理
telegram_message_react	设置或移除用户对一条消息的表情回应	覆盖
telegram_message_pin	置顶或取消置顶一条消息	覆盖
telegram_chat_mark_read	将聊天或某个论坛话题标记为已读，最多标记到指定消息，不会标记得更远	幂等

默认情况下，actions 工具集处于关闭状态：它会更改其他人已经读过的内容。通过 toolsets 或 tools 启用它。编辑和删除操作只能针对用户自己的消息；删除操作 始终对所有人生效，无法撤销，并且每次都会询问确认。回应只能使用一个标准表情符号， 并会替换用户之前的回应（不接受自定义和付费回应）。置顶操作默认不发送通知，除非 设置了 notify；在私聊中，除非设置了 both_sides，否则只会为用户自己置顶。 仅当用户提出请求时才会执行标记已读操作；它会标记到指定消息为止，不会向后标记， 并且会让发送者看到消息已读。每项操作都需要同步服务处于运行状态。already 表示操作已经完成；uncertain 表示操作可能已经执行，因此再次请求前应先检查聊天。 该技能为 telegram-actions，在 Claude Code 中显示为 telegram-tools:telegram-actions，在 Hermes 中显示为 telegram-tools:actions。

添加工具

1. 在 src/core/<domain>/<verb>.ts 中使用 defineTool 编写规范：包括 ID <prefix>_<domain>_<verb>、标题和描述、Zod 参数和输出架构、所属工具集和写入类别， 以及 execute(args, context)。写入工具还需提供 targets(args, context)：说明调用 会写入什么内容，以便权限规则明确指定目标。
2. 在规范旁边编写测试（<verb>.test.ts），通过 invoke 调用工具，就像各入口的调用 方式一样。运行程序的工具应针对 PATH 上该程序的假实现进行测试；测试不会连接 真实服务。
3. 在 src/tools.ts 中列出该工具。将新工具集添加到 src/project.ts 的 toolsets 中（如果默认启用，还需添加到 defaultToolsets），并将工具读取的设置之外的变量 添加到 toolVariables。
4. 添加或更新该工具集的技能文件 skills/<prefix>-<toolset>/SKILL.md，其 frontmatter 中的 metadata 需列出该工具集。
5. 运行 pnpm run build && pnpm run manifests，将工具列入 plugin.yaml，并将其变量 列入 Codex 的清单，然后在“工具和技能”下对其进行说明。

docs/conventions.md 说明了每个步骤所遵循的规则。

读取和写入

每个读取工具都命名为 <prefix>_<domain>_read。读取操作可以在不询问的情况下运行； 写入操作会由执行框架确认。

执行框架	无需询问即可读取
OpenCode	始终如此；插件只会在写入前询问
Claude Code	~/.claude/settings.json 中 permissions.allow 下的规则 mcp__plugin_telegram-tools_telegram-tools__*_read
Codex	始终如此；Codex 会在不询问的情况下运行声明了 readOnlyHint 的工具，读取工具也如此
Grok Build	grok --allow 'MCPTool(telegram-tools__*_read)' --allow 'MCPTool(telegram_*_read)'（两条规则；见下文）
Antigravity	permissions.allow 中的规则 mcp(telegram-tools_telegram-tools/<tool id>)，每个读取工具一条
Hermes	始终如此；插件只会在写入前询问

哪些情况下会询问写入操作，哪些情况下不会：

• OpenCode 不会要求任何操作匹配规则，因此写入操作会在无人询问的情况下运行，除非有规则要求询问：添加 OpenCode 下所示的 telegram_* 规则。
• 在 codex exec 模式下的 Codex 和在 grok -p 模式下的 Grok Build，会拒绝无法询问是否执行的写入操作，除非事先已允许。
• Grok Build 通过其 use_tool 工具调用插件的工具，而且 Agent 通常会在未指定服务器名称的情况下直接报出工具名。Grok 会根据给定的名称检查规则，因此仅有带服务器名称的规则无法匹配首次调用。第二条规则可以匹配简短名称；写入操作仍不会匹配任何一条规则。
• Antigravity 会在任何未被规则允许的 MCP 工具运行前询问，包括读取操作；它将插件的服务器命名为 telegram-tools_telegram-tools（插件名称，然后是服务器名称）。agy -p 会拒绝无法询问是否运行的工具。
• Hermes 的 hermes chat -q 会拒绝无法询问是否执行的写入操作；hermes -z 和 --yolo 会跳过审批，因此写入操作会在无人询问的情况下运行。

设置

每个入口点都使用相同的设置。标志优先于其环境变量，选项或设置也优先于变量。

设置	标志	变量	含义
toolsets	--toolsets	TELEGRAM_TOOLS_TOOLSETS	启用的工具集，或 all；默认启用 src/project.ts 中列出的名称
read_only	--read-only	TELEGRAM_TOOLS_READ_ONLY	不注册任何会写入的工具；优先级高于其他所有设置
tools	--tools	TELEGRAM_TOOLS_TOOLS	按 ID 添加单个工具，不受其所属工具集影响
exclude_tools	--exclude-tools	TELEGRAM_TOOLS_EXCLUDE_TOOLS	按 ID 移除单个工具；优先级高于 tools 和 toolsets
confirm	--confirm	TELEGRAM_TOOLS_CONFIRM	仅适用于 MCP 服务：根据约定使用 harness（默认）或 elicitation
language	--language	TELEGRAM_TOOLS_LANGUAGE	仅适用于原生插件：审批提示词所用的语言，例如 ja
emoji	—	—	仅适用于 Hermes：按工具集名称设置显示在每个工具集旁的表情符号（留空 "" 表示不显示）
state_dir	--state-dir	TELEGRAM_TOOLS_STATE_DIR	各标签的状态存放位置；默认为 $XDG_STATE_HOME/telegram-tools
download_dir	--download-dir	TELEGRAM_TOOLS_DOWNLOAD_DIR	telegram_file_save 保存接收文件的位置，每条消息对应一个文件夹；默认为 ~/Downloads/telegram-tools；工具会读取此设置，无需重启服务
download_max_mb	--download-max-mb <n>	TELEGRAM_TOOLS_DOWNLOAD_MAX_MB	下载文件的最大大小，单位为 MB；整数范围为 1..2000，默认为 100；工具会读取此设置，无需重启服务
send_dirs	--send-dirs	TELEGRAM_TOOLS_SEND_DIRS	除工作目录外，允许发送文件的目录；使用绝对路径，默认无；工具会读取此设置，无需重启服务
keep_disappearing	--keep-disappearing	TELEGRAM_TOOLS_KEEP_DISAPPEARING	为用户保留阅后即焚和仅查看一次的消息；默认关闭；由 sync 和 service install 读取，更改后请再次运行 service install
channels	--channels	TELEGRAM_TOOLS_CHANNELS	列出、读取、镜像频道并向频道发送消息；默认关闭，见下文；由 sync 和 service install 读取，更改后请再次运行 service install

在标志或变量中，列表以逗号分隔。各运行环境读取这些列表的位置：

• OpenCode 使用上文所示的插件 options，其中列表为数组， read_only 为布尔值，state_dir 和 download_dir 为路径， download_max_mb 为数字，send_dirs 为路径数组，并会回退到 环境变量。V2 在后台服务中运行插件，该服务会保留启动时的环境： 在 opencode run 启动时设置的变量不会生效，除非在该环境中 重启服务（opencode service restart）。V1 在自己的进程中运行插件。

• Hermes 在 config.yaml 中使用 plugins.entries.telegram-tools.settings：

  plugins:
    entries:
      telegram-tools:
        settings:
          read_only: false
          exclude_tools: []
  

  如果没有设置 language，审批卡片会采用 Hermes 自身的 display.language（或 HERMES_LANGUAGE），也就是审批按钮使用的语言； 否则会使用英语。插件会将自身的环境传递给它运行的命令行，因此这些变量也有效。 正在运行的网关会保留启动时的环境；更改变量后请重启网关 （hermes gateway restart）。

• Claude Code、Grok Build 和 Antigravity 不带标志启动插件的服务端， 并向其传递客户端的环境，因此请在运行该工具框架的环境中设置变量。

• Codex 只向插件的 MCP 服务传递少量基本变量（例如 PATH 和 HOME）， 以及插件清单中列出的变量，也就是上文的变量：请在运行 Codex 的环境中设置它们。 工具除设置项外读取的变量，应添加到 src/project.ts 中的 toolVariables； pnpm run manifests 会在设置项的变量之后将其添加到清单中。若要传递标志， 或向服务提供软件包未列出的变量，请改为在 Codex 的 config.toml 中 的 [mcp_servers] 下添加服务，而不要使用插件：标志放在 args 中， env_vars 用于指定从 Codex 环境转发的变量，env 用于设置固定值。

  [mcp_servers.telegram-tools]
  command = "npx"
  args = ["-y", "@craftsamo/telegram-tools@<version>", "--read-only"]
  env_vars = ["TELEGRAM_TOOLS_TOOLSETS"]
  

账号与同步服务

这些工具通过 mtcute 以用户本人账号的设备身份登录， 需要使用你在 my.telegram.org 注册的 api_id 和 api_hash。它们绝不会读取其他客户端的数据。

• 每个已登录会话都有一个标签，由 1 到 24 个小写字母、数字和 _ 组成（登录时未命名则使用 default）。工具的 account 参数用于选择标签； 只有一个会话登录时，可以省略此参数。
• 每个标签的状态都保存在一个目录中，即 <state_dir>/<label>/（模式 700）：其中包括会话和应用凭据、mtcute 的存储、镜像、服务套接字，以及 incoming/（用于存放传输中文件的短期副本）。state_dir 默认为 $XDG_STATE_HOME/telegram-tools，或 ~/.local/state/telegram-tools。请勿将其纳入共享备份：会话可以代你读取和发送消息。
• 同步服务持有每个标签唯一的连接，并维护镜像。镜像中保留的聊天会从镜像读取； 仅列出的聊天则通过服务实时读取。服务开始跟踪某个聊天后，历史记录便从此时开始； fetch 会添加更早的历史记录。
• 新的登录会显示在你的其他设备上，而 Telegram 会结束超过账号设置中指定时长未使用的会话。

登录并运行同步服务

开始之前，请在 my.telegram.org 注册应用 （API 开发工具），以获取 api_id 和 api_hash。这些工具需要 Node.js 24 或更高版本。支持 macOS 和 Linux。

# Log in: on your phone, open Telegram > Settings > Devices > Link Desktop Device,
# and scan the QR code this prints.
telegram-tools-cli login --account work

# Start receiving at logon, and restart after a failure.
telegram-tools-cli service install --account work
telegram-tools-cli service status --account work

只有一个标签时可以省略 --account（login 会将新标签命名为 default），并且每条命令都像这些工具一样接受 --state-dir。

命令	功能
login [--account <label>] [--phone | --telethon]	通过 QR 码（默认）、手机号和验证码（--phone），或 Telethon v1 字符串会话（--telethon）登录
sync [--account <label>] [--keep-disappearing] [--channels]	在前台运行同步服务，将日志输出到标准错误，直到服务停止
service install | uninstall | status [--account <label>]	将同步服务注册为 launchd 代理（macOS）或 systemd 用户单元（Linux）、移除该服务，或报告其状态
logout [--account <label>]	结束 Telegram 会话并保留镜像，同时移除本地会话存储
remove --account <label> [--yes]	卸载服务并永久删除该标签对应的目录；需使用 --yes 或重新输入标签确认

• 登录：默认情况下，login 会显示二维码。请在手机上的 Telegram 中依次前往“设置”→“设备”→“关联桌面设备”进行扫描。--phone 使用电话号码和登录验证码登录；--telethon 导入 Telethon v1 字符串会话，该会话通过终端中不回显的输入或标准输入读取。如果你的账号启用了两步验证密码，login 会以不回显的方式提示输入。设置了 TELEGRAM_TOOLS_API_ID 和 TELEGRAM_TOOLS_API_HASH 环境变量时会使用它们；否则，login 会提示输入这两个值（哈希值不回显），并将其保存到 <state_dir>/<label>/app.json（权限模式为 0600）。
• 服务的工作方式：首次启动时，服务会获取聊天列表，并分批抓取过去 30 天内活跃聊天的最新 50 条消息，同时控制抓取频率以避免触发限流。之后，每条更新到达时都会存入镜像，聊天列表每 30 分钟刷新一次，并补齐消息历史中的缺口。超级群组和频道仅在同步列表中时才会被镜像（最多 30 个）；频道还需要启用 channels 设置。
• 日志位置：在 macOS 上，服务会将日志写入 service install 所显示的文件：~/Library/Logs/io.github.craft-agent.telegram-tools/<label>.log。在 Linux 上，日志写入 systemd 用户日志（service status 显示的 journalctl --user -u <unit>）；运行 loginctl enable-linger，即可在你注销后继续运行服务。
• 在 macOS 上，“登录项”中会将服务列为 telegram-tools-sync-<label>：Agent 通过该启动脚本启动；service install 会将脚本写入 ~/Library/Application Support/io.github.craft-agent.telegram-tools/，service uninstall 会将其删除。在那里关闭该项目会停止同步。
• 服务更新和重启：service install 会记录此软件包和 Node 的可执行文件路径，因此更新其中任意一项，或更改 keep_disappearing 或 channels 后，都要再次运行 service install。如果 Node 的路径包含其版本号（例如使用版本管理器时），service install 会记录一个位于不含版本号路径下的 PATH 中的 node，该 node 会启动同一个 Node；如果不存在这样的 node，则会发出警告。随后，该 node 会运行版本管理器当前设为活动版本的 Node。使用此版本安装服务后，如果记录的程序已不存在，service status 和 telegram_account_read 会提示这一情况。服务发生故障后会在一分钟后重启；但如果 Telegram 结束了会话，服务会保持停止状态。
• 每个标签只能有一个连接：如果 Telegram 检测到同一个授权密钥同时从两个位置连接，可能会撤销该密钥。服务运行期间，login、logout 和 remove 会拒绝执行；请先停止服务（运行 service uninstall，或停止前台 sync）。
• 注销和删除：logout 会结束 Telegram 上的会话并保留镜像，只删除会话存储。remove 会卸载服务并永久删除该标签的目录；在 macOS 上也会删除服务日志（service uninstall 会保留日志）；在 Linux 上，日志会保留服务的记录。如果无法连接到 Telegram，会话会在本地删除；请在 Telegram 中依次前往“设置”→“设备”以结束会话。
• 设备会话：新登录会显示在你的其他设备上。达到“设置”→“隐私和安全”→“如果离开时间超过”中设定的时长后，Telegram 会结束未使用的会话；届时请重新登录。telegram_account_read 会告知 Agent 某个标签需要执行的步骤。

非官方客户端，以及 Telegram 条款的规定

该软件包并非由 Telegram 制作或认可。你需要注册自己的应用 （API 条款 §2.1），该软件包以及服务登录时使用的设备名称会表明它是非官方的（§2.2、§2.3）。

• Telegram 条款禁止将平台数据用于 AI。 §1.5 禁止使用平台数据训练或部署 AI；广义解读也涵盖 Agent 读取你自己的聊天内容。非官方客户端会受到监控，滥用行为可能导致账号被冻结或封禁。
• keep_disappearing 和 channels 默认关闭。 保留阅后即焚消息违反 §1.4。开启后，同步服务还会在阅后即焚、阅后即看和自毁消息到达时保留其文件（每个文件最大 100 MB，绝不保留程序或归档文件），因此 Telegram 删除这些文件后，telegram_file_save 仍可保存它们；关闭此选项后，这些文件会在服务下次启动时删除。对于频道，API 条款 §3.3 要求展示频道内容的应用显示赞助消息。服务绝不会获取或展示赞助消息（以免不受信任的提示词传入模型），开启 channels 的人需自行承担 §3.3 所述风险。关闭 channels 时，不会列出、读取、镜像或加入同步列表中的任何频道；同步服务会在下次启动时从镜像中删除所有频道及其镜像消息。

目录结构

• src/project.ts — 软件包名称、工具 ID 前缀、设置前缀、工具集以及工具读取的其他变量。
• src/core/ — 工具约定和工具本身，不依赖任何运行框架，也不包含项目名称。
• src/tools.ts — 所有工具的列表，每个入口点都会注册这些工具。
• src/words.ts — 各语言版本的工具用语翻译，原生插件会在其审批提示词中使用这些内容。
• src/mcp/ — MCP 服务，构建为 dist/mcp.js，并由 telegram-tools 运行。
• src/opencode/ — OpenCode 插件，构建为 dist/opencode.js。
• src/cli/ — Hermes 插件调用的命令行程序，构建为 dist/cli.js，并由 telegram-tools-cli 运行。
• src/hermes/、plugin.yaml 和 __init__.py — Hermes 插件。
• skills/ — 每个工具集对应一个技能，路径为 skills/<name>/SKILL.md；所有支持技能的运行框架都会从软件包或插件根目录加载这些文件；原生插件只会加载已启用工具集的技能。
• .claude-plugin/、.codex-plugin/、.agents/plugins/、.mcp.json、.antigravity-plugin/ 和 mcp_config.json — 其他运行框架的插件清单。Codex 会读取 .codex-plugin/plugin.json；根目录中的 plugin.json 会使它将该插件作为 Agent Plugin 加载，其工具数量上限会隐藏超出固定大小的工具。根目录中的 .mcp.json 是 Grok Build 读取的配置（其中包含 ${CLAUDE_PLUGIN_ROOT}，Grok Build 和 Claude Code 都会展开此变量）；在 Claude Code 中处理此仓库时，请拒绝它通过该文件提供的项目 MCP 服务。

发布流程见 RELEASING.md。

许可证

AGPL-3.0 with Commons Clause