Better-TG-CLI (Telegram)

https://github.com/user-attachments/assets/d143f7c7-7d50-439c-b373-cbcbff5a6675

一款非官方、适合 Agent 使用的 Telegram 命令行客户端，可使用你自己的账号运行 （通过 teleproto 使用 MTProto，TL layer 229）。命令为 telegram：约有 60 个命令，可用于读取、搜索、写入、管理机器人和群组，以及导出内容；其设计旨在让 AI Agent（Claude Code、Codex 等）能够以低成本、安全地操作。

$ telegram inbox -n 3
48 unread in 7 chats (showing 3)
1234567890 user unread=2 Alice @alice | see you at 7?
-1001234567 supergroup muted unread=41 Rust Seattle @rust_sea | anyone tried 1.90?
-1009876543 channel unread=5 Changelog | v2.4 is out
$ telegram read @alice -n 1 --json
{"chatTitle":"Alice","messages":[{"id":812,"date":"2026-09-27T10:02:11.000Z","sender":"Alice","senderId":"1234567890","text":"see you at 7?"}]}

警告

你的账号，风险自负。 这是一款以你的身份登录的非官方客户端。Telegram 可能会限制或冻结表现得像机器人的账号。新账号、批量发送消息、大量加入群组或邀请他人，以及任何看起来像垃圾信息的行为，风险最高。请像使用 Telegram 本身一样使用它；除非确有需要，否则不要启用写入功能，并在允许 Agent 写入前阅读 SECURITY.md。作者不对账号受到限制承担责任。

目录： 为何分叉 · 安装 · 登录 · 用法 · MCP 服务 · 常见问题 · 开发 · 隐私 · 许可证

为什么采用这个分支

这是 skillhq/telegram 的一个分支，经过重新设计以适配 Agent：

• 更新的 Telegram 层。 Bot 回复中的富内容（layer 228+）会显示真实文本，而不是 (no text)。你可以按下 Bot 按钮（click）并浏览 Bot 菜单。
• 输出节省 Token。 在 TTY 外运行时，每个条目占一行紧凑输出，ID 放在最前面；JSON 也只占一行，并省略空字段。--max-text 可截断较长的帖子。telegram help-all -g <word> 会从代码生成并打印所有标志。
• 精确读取。 --since/--until、--unread、话题和频道评论、论坛主题、按 ID 执行 get、按类型、发送者或日期筛选搜索结果，以及用于已保存消息的 me / Избранное，都支持真正的分页。
• 默认安全。 账户默认为只读，直到有人运行 write-access on [--for 1h]，并在终端提示或 macOS 对话框中确认。这样 Agent 无法自行启用写入权限。每次写入都会记录到 ~/.config/tg/audit.jsonl。密钥保存在 macOS Keychain、Linux Secret Service 或 1Password 中。
• 小巧且独立。 npm 包是一个 0.3 MB 的文件，运行时依赖为零。Homebrew 安装的独立二进制文件无需 Node。

安装

brew install thevilfer/tap/better-tg-cli   # standalone binary, macOS and Linux
npm install -g better-tg-cli               # Node >= 20, any OS

在 Windows 上（实验性支持），可使用 Scoop 或 npm 安装：

scoop bucket add thevilfer https://github.com/TheVilfer/scoop-bucket
scoop install better-tg-cli

Windows 版 telegram.exe 未进行代码签名，因此 SmartScreen 可能会对下载的发行版本发出警告。

无论使用以上哪种方式安装，telegram update 都可以升级现有安装。在终端中，CLI 每天检查一次新版本。Agent 和管道不会看到该通知；设置 TG_NO_UPDATE_CHECK=1 可关闭检查。

在 macOS 上手动从 Releases 下载二进制文件？该文件未经公证，因此只需运行一次 xattr -d com.apple.quarantine ./telegram 即可移除隔离标记。Homebrew 会自动处理。

不要安装 @skillhq/telegram。它是基于 GramJS（layer 198）的旧版上游构建。

每个渠道都从同一个发行版本获取相同版本：

渠道	提供内容	安装方式
Homebrew	独立二进制文件	brew install thevilfer/tap/better-tg-cli
npm	CLI 和 MCP 服务（Node 20+）	npm install -g better-tg-cli
Scoop（Windows，实验性支持）	独立的 telegram.exe	scoop bucket add thevilfer https://github.com/TheVilfer/scoop-bucket，然后运行 scoop install better-tg-cli
GitHub Releases	二进制文件和 SHA256SUMS	手动下载
Claude Code 插件	技能和 MCP 服务	见下文
Claude Desktop 扩展	MCP 服务，使用 Claude 内置的 Node 运行	下载 .mcpb 并打开
Grok Build 插件	技能和 MCP 服务	见下文
Gemini CLI 扩展	技能和 MCP 服务	gemini extensions install https://github.com/TheVilfer/better-tg-cli
Cursor、VS Code	MCP 服务	一键按钮
Grok Bot	通过 HTTP 从你的 Mac 运行的 MCP 服务	见下文
CLI 本身	适用于 Claude Code、Codex、Cursor、Gemini CLI 等另外 7 款工具的 Agent 技能	telegram skill install
skills.sh	适用于任何 Shell Agent 的 Agent 技能	npx skills add TheVilfer/better-tg-cli
MCP Registry	MCP 服务条目 io.github.TheVilfer/better-tg-cli	通过你的 MCP 客户端

Claude Code 插件

一次安装即可同时获取技能和 MCP 服务：

/plugin marketplace add TheVilfer/better-tg-cli
/plugin install better-tg-cli@better-tg-cli

它通过 npx 运行 MCP 服务，因此只需 Node 20+。在终端中运行 telegram auth --qr （或 npx better-tg-cli auth --qr）登录一次即可。

Codex 插件

同一技能和 MCP 服务也可作为 Codex 插件使用（也会显示在 ChatGPT 桌面应用中）：

codex plugin marketplace add TheVilfer/better-tg-cli
codex plugin add better-tg-cli@better-tg-cli

Grok Build 插件

Grok Build 会一起安装同一插件、技能和 MCP 服务：

grok plugin install TheVilfer/better-tg-cli --trust
# or add the marketplace first, then install from the /plugins menu:
grok plugin marketplace add TheVilfer/better-tg-cli && grok plugin install better-tg-cli --trust

作为 Agent 技能

此技能（skills/better-tg-cli）教会任何能够使用 shell 的 Agent （Claude Code、Codex、Cursor、Gemini CLI、OpenCode 等）安全地使用 CLI。它会检查设置，不会自行登录，所有写入操作都需经你批准，并避免容易导致封号的操作模式。 CLI 自带此技能并会自行安装，因此技能始终与你的版本一致：

telegram skill install                  # every supported agent found on this machine
telegram skill install -a claude-code codex
telegram skill status                   # installed, outdated, linked or missing, per agent

它支持 Claude Code、Codex、Cursor、Gemini CLI、GitHub Copilot、Grok Build、OpenCode、Goose、 Droid、Windsurf 和 Pi（telegram skill status 会列出这些文件夹）。运行 telegram update 后，再次运行它即可更新技能。符号链接形式的技能文件夹会保持不变，除非你传入 --force。对于其他 Agent，请使用 skills CLI：

npx skills add TheVilfer/better-tg-cli          # pick agents interactively
npx skills add TheVilfer/better-tg-cli -g -a claude-code -a codex -y

登录

通过你的 Agent（最简单）：让它设置 Telegram，或自行运行 telegram onboard。它会打开一个位于 127.0.0.1 的页面，你可以从 better-tg-cli.com 获取登录密钥（页面会自动跳转回来），也可以输入自己的密钥，然后扫描二维码并输入 2FA 密码。Agent 只会启动命令并等待：它不会看到登录密钥、二维码或密码。此页面仅在随机生成的密钥路径上响应，完成后会关闭。

使用自己的 API 密钥（默认方式）：

1. 打开 https://my.telegram.org/apps，创建应用，并复制其 api_id 和 api_hash。
2. 运行 telegram auth --qr 并输入这些密钥。然后在手机上前往“设置”→“设备”→“关联桌面设备”，扫描二维码。如有 2FA 密码，请输入。普通的 telegram auth 会改为要求你输入手机号码和登录验证码。如果在浅色终端主题下无法扫描二维码，请使用 TG_QR_INVERT=1 运行。

使用登录密钥。 使用登录密钥时，无需自己的密钥。可从 better-tg-cli.com 获取（使用验证码确认邮箱；该页面还提供安装指南），也可向维护者获取。 运行 telegram auth --login-key --qr 并粘贴密钥，或通过 TG_LOGIN_KEY=… 传入，或使用 --login-key -。登录服务（broker/）仅为本次登录发放应用密钥一次。 api_hash 不会保存在你的设备上。登录密钥为个人专用，可在最多 3 台电脑上使用，并且可以撤销。在 0.37 之前，该密钥称为邀请密钥：--invite 和 TG_INVITE 仍然可用。

会话存储在 macOS 钥匙串（服务 tg-cli）中，也可使用 --op-vault <vault> 存储在 1Password 中。telegram logout 会将其删除。在 Linux 上，会话通过 secret-tool 存储到 Secret Service（GNOME Keyring、KWallet、KeePassXC），这需要安装 libsecret-tools 软件包。已保存在配置文件中的会话会自动迁移到该处。若没有任何密钥存储，会话将保存在 ~/.config/tg/config.json5 中（模式为 0600），并禁用写入命令。 在 Linux 上，启用 write-access on 需要在终端提示符下确认。在 Windows 上，密钥存储在 %APPDATA%\tg\secrets.dpapi 中，并使用 DPAPI 加密，以供你的 Windows 用户使用（只有你能在此设备上解密）；如果没有终端，启用 write-access on 时会弹出“是/否”窗口。

用法

telegram chats --type channel                 # one line per chat, ID first
telegram read "Chat" --since 1h               # exact range, newest first (--asc to flip)
telegram read @channel --thread 123           # comments under a post
telegram search "invoice" --chat "Work" --type document
telegram get "Chat" 812 813                   # exact messages by ID
telegram download "Chat" 812                  # save the attached file
telegram sync --chat "Chat" --output ./export --resume   # incremental markdown export

telegram drafts                               # saved but unsent drafts
telegram admin-log "Team"                     # a group's recent admin actions
telegram profile-photos @alice                # a user's profile photos
telegram read @channel -n 20 --full           # every message stat (views, reactions, flags, media)
telegram stats "Mock News" --graphs           # full channel stats + growth graphs; --message <id> / --story <id> too
telegram sessions ; telegram stars            # active login sessions; Telegram Stars balance & transactions
telegram invites "Team" --requests            # a chat's invite links, or its pending join requests

telegram write-access on --for 1h             # a human confirms this
telegram send @alice "on my way"
printf '%s' "$text" | telegram send @alice -  # long or multi-line text: from stdin, no quoting problems
telegram reply "Chat" 812 "on it" --silent
telegram click @SomeBot 4410 "Settings"       # press an inline button
telegram pin-chat @alice                      # pin a chat; mark-unread / delete-dialog too
telegram edit-permissions "Team" @alice --mute --until 1d   # restrict a member; --lift to undo
telegram topic create "Dev Forum" "Release 2.0"            # forum topics: create/edit/close/reopen/pin

telegram api messages.GetAllDrafts            # call any raw TL method (full API reachability)
telegram api channels.GetAdminLog --params '{"channel":{"_chat":"Team"},"limit":20,"q":""}'
telegram messages get-history --peer @durov --limit 10      # or a typed command per TL method
telegram account get-authorizations           # telegram <namespace> --help lists a namespace
telegram help get-config                      # telegram ping, telegram req-pq, … for root methods

读取命令支持 --json，其中一些还支持 --markdown。read/get/search/inbox/watch 支持 --full（别名 --stats），以包含每条消息的所有统计信息（浏览量、转发量、完整的回应明细、评论、标记、富媒体元数据）——不使用此选项时，默认输出保持不变。 使用 telegram help-all 查看所有命令。reference.md 介绍了标志列表无法说明的行为：输出结构、线程、机器人按钮、管理员命令和故障排查。通用命令 telegram api <namespace.Method> 可访问 100% 的 Telegram 客户端 API，而 823 个 TL 方法也都有各自带类型的顶层命令 telegram <namespace> <method>（根方法也包括在内，例如 telegram ping）；这些命令由架构生成，与 api 具有相同的拒绝规则和读写保护。当命名空间名称与精选命令（stats、stories、contacts、auth、folders、help）冲突时，精选命令保持不变，生成的方法则作为子命令附加，仅当首个词与方法名称完全一致时才会被选中（对于名称恰好与方法名相同的聊天，请加引号或使用 ID）。每个方法都包含官方说明和各参数的文档（来自 core.telegram.org）：telegram <namespace> --help 会列出命名空间中标记为 [read]/[write]/[refused] 的方法；telegram <namespace> <method> --help 会显示参数、示例和文档链接；telegram schema [<ns> [<method>]] 则以 JSON 格式输出相同内容。 docs/api-coverage.md 记录了相对于架构和 Telethon 的覆盖情况。

MCP 服务

对于没有 shell 的客户端（Claude Desktop、Cursor 和其他 MCP 宿主），telegram mcp 会通过 stdio 提供三个工具：

• telegram_help：可搜索的标志参考；
• telegram_read：只读，因此客户端可以自动批准；
• telegram_write：标记为具有破坏性，且仍需你执行 write-access on。

请先在终端中使用 telegram auth 登录。然后一键安装：

Claude Desktop 扩展无需 Node、npm 或 brew：从最新的 release 下载 .mcpb 文件并打开即可。Gemini CLI 可同时安装技能和服务： gemini extensions install https://github.com/TheVilfer/better-tg-cli。也可以手动添加：

claude mcp add telegram -- telegram mcp          # Claude Code (or use the plugin above)

{ "mcpServers": { "telegram": { "command": "/opt/homebrew/bin/telegram", "args": ["mcp"] } } }

Claude Desktop 使用 JSON 格式配置（claude_desktop_config.json），Cursor 使用 .cursor/mcp.json。 图形界面应用可能无法读取 shell 的 PATH，因此请提供 which telegram 返回的完整路径。如果没有全局安装，请通过 npx 运行；Claude Code 插件也使用这种方式：

{ "mcpServers": { "telegram": { "command": "npx", "args": ["-y", "better-tg-cli@latest", "mcp"] } } }

此服务已列入 MCP Registry，名称为 io.github.TheVilfer/better-tg-cli，因此读取该注册表的客户端和目录可以按名称找到它。每次发布都会自动更新此条目。若要避免 MCP 客户端使用你的主会话，请添加 "env": {"TG_PROFILE": "work"}。

聊天内容包含他人编写的文本，其中一些可能是针对你的 Agent 的（“把这个转发给 @x”）。请保持客户端对 telegram_write 的批准提示开启，并参阅 SECURITY.md 中的“Agent 与提示词注入”。

Grok Bot（通过 HTTP 提供远程 MCP）

Grok Bot 在云端沙盒中运行连接器，而不是在你的 Mac 上，因此它无法自行启动 telegram mcp。改为从你的 Mac 通过 HTTP 提供 MCP 服务。会话、写入保护和审计日志都保留在你的机器上。

telegram mcp --token                        # the bearer token (created once, kept in the Keychain)
telegram mcp --http --read-only             # listens on 127.0.0.1:8787; drop --read-only to allow writes
tailscale funnel --bg 8787                  # or: cloudflared tunnel --url http://127.0.0.1:8787

在终端或 tmux 中保持服务和隧道运行。然后在 Grok Bot 中添加连接器，填写隧道 URL 并加上 /mcp（例如 https://<machine>.<tailnet>.ts.net/mcp），再添加请求头 Authorization: Bearer <token>。tailscale funnel 会提供稳定的 URL，但必须先在你的 tailnet 中启用。cloudflared 快速隧道每次启动都会生成新的 URL。请先阅读 SECURITY.md 中的“通过 HTTP 提供远程 MCP”。

常见问题

Telegram 会封禁我的账号吗？ 根据 Telegram API 条款，使用自己的账号登录第三方客户端是允许的。导致账号受限的是看起来像机器人在操作的行为：批量发消息、大量加入群组或发出邀请、发送垃圾信息，以及全新账号短时间内进行大量操作。像平时使用 Telegram 一样使用即可。该技能会指示 Agent 避免这些行为。

这是机器人吗？ 不是。它通过 MTProto 以你的身份登录，就像 Telegram Desktop 一样，能看到你能看到的内容。机器人无法读取你的聊天记录；它可以。

Agent 可以自行发送消息吗？ 只有你启用写入功能后才可以。telegram write-access on 会要求你在终端或 macOS 对话框中确认，Agent 无法代为确认。启用写入后，必须指定确切的聊天对象，并且每次操作都会记录。通过 MCP 写入时，客户端可以请求使用单独的工具，每次都由你批准。详情请参阅 SECURITY.md。

读取消息会将其标记为已读吗？ 不会。read、inbox 和 search 不会将聊天标记为已读。只有 telegram mark-read 会将其标记为已读。

我需要自己的 API 密钥吗？ 需要，可从 my.telegram.org/apps 获取。密钥免费，创建只需一分钟。使用来自 better-tg-cli.com 的登录密钥时，运行 telegram auth --login-key --qr 即可免密钥登录。

会话存储在哪里？谁能看到我的消息？ 会话存储在 macOS Keychain、Linux Secret Service 或 1Password 中。CLI 直接与 Telegram 通信，不收集分析数据。除此之外，它只会连接 npm 进行每日版本检查，以及在使用登录密钥登录时连接登录服务。请参阅 PRIVACY.md。

可以使用多个账号吗？ 可以，使用 TG_PROFILE 即可：每个配置文件都有独立的登录信息、配置和 Keychain 项目，例如 TG_PROFILE=work telegram auth --qr。正确切换账号的功能正在 #5 中跟踪。

可以在 Windows 上使用吗？ 可以，但仍处于实验阶段：使用 scoop install better-tg-cli 或 npm 安装。密钥使用 Windows DPAPI 存储，CI 也会在 Windows 上运行测试，但相比 macOS 和 Linux，Windows 上的实际使用测试还较少。遇到问题请在 issue 中报告。

可以通过 Grok Bot、ChatGPT 或其他云端 Agent 使用吗？ 云端 Agent 无法在你的电脑上启动程序，因此请通过 HTTP 运行 MCP 服务，并通过隧道访问。请参阅 Grok Bot。

如何更新？ 运行 telegram update。它会使用你安装时所用的渠道：Homebrew、npm 或发布的二进制文件。 如果你通过 telegram skill install 安装了 Agent 技能，请再次运行该命令以更新。

开发

DEVELOPMENT.md 介绍了：

• 从源代码运行（scripts/tg-dev）；
• 独立的开发配置文件（TG_PROFILE），绝不会触及你的真实会话；
• Telegram 测试服务器；
• 编辑器调试和测试。

发布通过 scripts/release.sh 完成（创建发布 PR；版本号取自 PR 标题），合并后再运行 scripts/release.sh tag。创建标签后会构建二进制文件，并发布到 GitHub Releases、npm（使用可信发布和来源证明）、Homebrew tap 及 MCP Registry。请参阅 CONTRIBUTING.md。

卸载

1. telegram logout 会删除已保存的会话。若也要在 Telegram 端结束会话，请前往 Telegram → Settings → Devices 将其终止。
2. telegram skill uninstall 会从已安装该技能的 Agent 中移除它。
3. 移除程序：brew uninstall better-tg-cli、npm uninstall -g better-tg-cli 或 scoop uninstall better-tg-cli。如果使用的是 Releases 中的二进制文件，请删除 telegram / telegram.exe。
4. 删除配置文件夹：~/.config/tg（Windows 上为 %APPDATA%\tg），以及你使用过的每个 TG_PROFILE 对应的 ~/.config/tg-<profile>。在 Windows 上，这也会删除 DPAPI 密钥文件。其他平台上的 api_hash 和写入权限标志会保留在密钥存储中：请在 Keychain Access 中删除 tg-cli 项（或运行 secret-tool clear service tg-cli），或删除 1Password 保险库中的对应项。

隐私

不进行任何分析。我们运行的唯一服务是可选的登录服务，它不会看到你的消息或会话。请参阅 PRIVACY.md，了解 CLI 会连接的 3 个主机以及它在本地存储的内容。

代码签名政策

Windows 二进制文件仅由 GitHub Actions 从此仓库构建（.github/workflows/release.yml），绝不会在个人电脑上构建。我们已申请 SignPath Foundation 提供的免费代码签名；签名服务启用后，发布版二进制文件将附带：由 SignPath.io 提供的免费代码签名，证书由 SignPath Foundation 提供。 在此之前，Windows 版 telegram.exe 不带签名；macOS 二进制文件采用临时签名。

• 提交者和审阅者：@TheVilfer
• 批准者（每个已签名的发布版本）：@TheVilfer
• 隐私政策：PRIVACY.md。CLI 仅会连接 Telegram、使用登录密钥登录时连接登录服务，以及在终端中为每日更新检查连接 npm registry（设置 TG_NO_UPDATE_CHECK=1 可关闭）。

许可证

MIT，详见 LICENSE。基于 Derek Rein 的 skillhq/telegram。与 Telegram 无关联，也未获其认可；“Telegram”是其所有者的商标。请遵守 Telegram API 服务条款 使用。