核心用法
tg-cli 是一款基于 Node.js 的命令行工具，通过 MTProto 协议直接与 Telegram 服务器通信，绕过官方 Bot API 的限制，实现完整的聊天记录读取和媒体下载功能。
安装与认证
npm install -g tg-mtproto-cli tg auth # 交互式输入 phone → OTP → api_id/api_hash
主要功能
tg chats：列出所有对话（私聊/群组/频道），支持--json结构化输出tg messages <chat>：读取消息历史，支持按数量-n、时间--after、话题--topic过滤tg download <chat> <msgId>：下载指定消息的媒体附件tg topics <chat>：获取论坛群组的话题列表tg accounts：多账户管理（添加、切换、重命名、删除）
典型工作流
# 提取某频道2月以来的所有文本 tg messages @channel --after 2026-02-01 --json | jq -r '.[].text // empty' # 批量下载最近50条消息中的图片 for id in $(tg messages @chat -n 50 --json | jq -r '.[] | select(.media.type == "photo") | .id'); do tg download @chat "$id" --out ./photos done
显著优点
1. 突破 Bot API 限制：MTProto 直接访问，无消息频率限制，可读取完整历史
2. 纯只读设计：官方明确无发送消息、修改群组等写操作，降低误操作风险
3. 多账户原生支持：通过 --account 或 tg default 切换，适合工作/个人分离场景
4. JSON 管道友好：所有命令支持 --json，与 jq 配合实现复杂数据处理
5. 凭证安全存储：api_id/api_hash 存入系统钥匙串（macOS Keychain/Windows Credential Vault/Linux Secret Service），非明文环境变量
潜在缺点与局限性
| 问题 | 说明 |
|------|------|
| 需官方 API 凭证 | 必须注册 my.telegram.org 获取 api_id/api_hash，有一定门槛 |
| 交互式认证 | `tg auth` 需真人输入手机+验证码，无法全自动化部署 |
| 会话文件敏感 | `~/.tg-mtproto-cli/sessions/*.session` 含授权密钥，泄露即账户风险 |
| 无官方背书 | 第三方实现（GitHub 用户 cyberash-dev），非 Telegram 官方工具 |
| Node 依赖 | 需全局安装 npm 包，对非 JS 生态用户不够轻量 |
适合人群
- 数据分析师：需要批量导出特定频道历史进行 NLP/舆情分析
- 合规审计人员：按法规要求归档企业 Telegram 工作群组
- 开发者：构建 Telegram 数据 pipeline，结合 cron + jq 做自动化监控
- 多账户用户：工作号与个人号需在同一设备快速切换
常规风险
1. 账户封禁：MTProto 非 Bot API，高频请求可能触发 Telegram 风控
2. 凭证泄露：api_id/api_hash 若被截图/日志记录，可构造相似客户端
3. 会话劫持：session 文件权限 600 仍可能被同机恶意进程读取
4. 误删风险：tg logout 永久清除会话，需重新交互认证
5. 供应链风险：npm 包更新依赖发布者账号安全，建议固定版本 tg-mtproto-cli@x.y.z
安全建议
- 启用 2FA 的 Telegram 账户优先使用此工具
- 定期清理
~/.tg-mtproto-cli/sessions/过期会话 - 在 CI/CD 场景中禁用此技能（因需交互式认证）