tgcli

tgcli

面向 AI Agent 的 Telegram 命令行工具技能。

安装

从 GitHub 安装此技能：

npx skills add dapi/tgcli --skill tgcli --agent '*' -g -y

安装命令行工具：

npm install -g @dapi/tgcli

进行一次身份验证：

tgcli auth

工具边界：tgcli 与 telegram-mcp

使用 tgcli 的场景	使用 telegram-mcp 的场景
读取／搜索／归档消息	编辑／删除／转发
查看／点击回调按钮	表情回应
发送文本／照片／文件和主题帖	高级交互操作
论坛主题列表／搜索
下载消息中的媒体
群组管理（加入请求、重命名、成员、邀请、加入／退出）	使用细粒度权限封禁／踢出／提升成员
频道／联系人标签和元数据
同步任务和归档监控
用于自动化的 JSON 输出

执行规则

• 如果找不到 tgcli，请安装：npm install -g @dapi/tgcli，然后首次登录时运行 tgcli auth。
• tgcli auth 只会对 Telegram 会话进行身份验证。使用 tgcli sync --once 或 tgcli sync --follow 来初始化／归档对话。
• Agent 工作流中始终添加 --json。
• 默认添加 --timeout 30s；对于耗时较长的实时读取，使用 --timeout 90s。
• 优先明确指定 --source archive|live|both，而不要依赖默认值。
• --source archive 只读取本地归档，即使未找到结果也是如此。使用 --source live 查询 Telegram，或使用 --source both 合并两者的结果。
• 在运行 tgcli server 或 tgcli sync --follow 时，读取归档消息、读取缓存标签以及运行 sync jobs list 都会使用只读 SQLite。实时读取和会更改存储的命令会使用所有者的本地私有套接字，即使 MCP 已禁用也是如此。没有所有者时，CLI 会自行获取这些命令所需的存储控制权。如果实时所有者的套接字不可用，必须先修复或停止该所有者，然后才能重试依赖所有者的命令；CLI 不会开启第二个会话。
• 当 Telegram 对服务启动时刷新对话进行频率限制时，服务仍可用，但会暂停待处理的同步任务。tgcli sync status --json 会显示 dialogRefreshDeferred: true；稍后通过同一个所有者运行 tgcli sync --once，重试刷新。遇到 FLOOD_WAIT 时，不要反复重试。
• 如果实时命令报告 UNKNOWN_RESULT，不要盲目重试发送操作或其他非幂等更改。在同一个所有者运行期间，使用返回的 requestId 执行 tgcli owner request <requestId> --json；如果请求仍在运行或结果未知，请先检查聊天或归档，再决定是否重试。
• --timeout 会取消所有者上的请求所涉及的 Telegram RPC 和上传，从而释放其实时槽位。但它无法撤回已发送至 Telegram 的更改：结果可能仍为 unknown，代码为 UNKNOWN_RESULT。对于大文件，请明确指定更长的超时时间。后台同步任务会独立于排入该任务的请求继续运行。
• 切勿使用 --since；tgcli 使用带 ISO 时间戳的 --after 和 --before。
• 切勿使用 tgcli sync --chat ...；顶层 sync 只会通过 --once / --follow 运行工作器。
• 要同步特定聊天：运行 tgcli channels sync --chat <id|@username> --enable 和／或 tgcli sync jobs add --chat <id|@username>，然后运行 tgcli sync --once 或 tgcli sync --follow。
• 如果不确定命令的格式，请先使用 tgcli <command> --help 核实，不要猜测标志。
• 在命令前使用全局选项 --account <id|alias|phone>，或设置 TGCLI_ACCOUNT，以选择具名账户。选择优先级为 --account → TGCLI_ACCOUNT → default。
• default 配置会保留旧版存储和现有授权。仅仅因为看不到具名配置，切勿运行 auth logout、移动会话或复制会话文件。
• 具名配置的配置文件、会话、消息数据库、锁、下载内容、同步任务和服务状态都彼此物理隔离。对此配置执行身份验证、读取、写入、同步和服务命令时，始终使用相同的账户选择器。
• 如果账户命令意外显示没有配置，或报告缺少配置，请检查 TGCLI_STORE：继承的临时／测试存储可能会隐藏生产环境的配置注册表。考虑更改任何身份验证设置之前，请先确定目标基础存储。
• 全局代理回退设置位于 ~/.tgclirc 中，格式为 proxy=<url>，适用于所有账户配置。有效优先级为 TELEGRAM_PROXY → 所选配置的 config.json → ~/.tgclirc。
• 发送格式控制：
  • --parse-mode markdown|html|none（不区分大小写）
  • 对于 send photo 和 send file，--parse-mode 需要 --caption
  • --reply-to <messageId> 回复特定消息；如果同时传入 --reply-to 和 --topic，则以 --reply-to 为准
  • --silent 发送时不播放通知声音
  • --no-forwards 可防止消息被转发／保存
  • --schedule <iso> 将消息安排在未来发送（ISO 8601，必须是未来时间，且不超过 365 天）
  • --caption-above 将说明文字显示在媒体上方（仅适用于 send photo／send file，需要 --caption）
  • --spoiler 将媒体模糊处理，直到用户点击（仅适用于 send photo／send file）
  • --retries <n> 在 send photo 遇到临时网络／传输故障时重试
  • --retry-backoff <ms|constant|linear|exponential> 控制 send photo 的重试延迟
  • --force-document 将照片／视频作为未压缩的文档发送（仅适用于 send file）
  • --retries <n> 失败时使用指数退避重试（默认值为 0）；发生重试时，JSON 输出会包含 retry_log 和 attempts
• Telegram Markdown 格式（使用 --parse-mode markdown 时）：
  • 粗体：**text**
  • 斜体：__text__（双下划线，不能使用单个 _）
  • 粗斜体：**__text__**（粗体标记包裹斜体标记）
  • 单个 _text_ 不支持斜体，会按原样显示下划线
  • 单个 *text* 不支持粗体，会按原样显示星号
  • 行内等宽字体：`text`
  • 代码块：三个反引号
  • Telegram Markdown 与标准 Markdown 不同——始终使用双标记
• 切勿删除锁文件（LOCK、database is locked）：等待后重试。
• 对于多行文本或任意用户编写的文本，请使用 scripts/send_text.py，并通过 stdin 传入正文。它会在不使用 shell 的情况下调用 tgcli，从而准确保留实际换行 和标点。
• 切勿使用 JSON.stringify(message) 构造 shell 命令，也不要在 --message 中放入 字面量 \\n 序列：Telegram 会显示反斜杠和字母 n，而不是换行。
• 发送多行文本后，请读回消息并确认 text 中包含实际换行符，而不是字面量 \\n 序列。

核心命令模式

账户

# Existing commands without a selector continue to use the default profile.
tgcli auth status --json --timeout 30s

# Register an isolated profile without contacting Telegram.
tgcli accounts add work --phone "+7 707 111 22 33" --alias office
tgcli accounts list --json

# Authenticate and use exactly one named profile.
tgcli --account work auth
tgcli --account office auth status --json --timeout 30s
tgcli --account +770****2233 messages search "invoice" --source live --json --timeout 30s

# Environment selection is useful for a dedicated service/process.
TGCLI_ACCOUNT=work tgcli sync --follow

账户选择器会根据稳定的配置文件 ID、规范化的电话号码或别名进行解析。如果选择存在歧义，或存储的 Telegram 用户 ID 与会话不匹配，请停止操作并检查配置文件；切勿回退到其他账户。

对于在应用内收到的登录验证码，请通过同一个已授权的目标配置文件读取 Telegram 官方服务聊天 777000。验证码可能会本地化，例如 Код для входа в Telegram: 或 Login code:。请根据授权请求时间戳筛选验证码，并通过 stdin 传递，而不要将其放入命令参数或日志中。

读取

tgcli messages list --chat <id|@username> --limit 50 --source archive --json --timeout 30s
tgcli messages list --chat <id|@username> --chat <id2> --limit 50 --source archive --json --timeout 30s
tgcli messages list --chat <id|@username> --topic <topicId> --after 2025-01-01T00:00:00Z --limit 100 --source archive --json --timeout 30s
tgcli messages show --chat <id|@username> --id <msgId> --source archive --json --timeout 30s
tgcli messages context --chat <id|@username> --id <msgId> --before 5 --after 5 --source archive --json --timeout 30s
tgcli messages list --chat <id|@username> --limit 50 --source live --json --timeout 90s
tgcli messages list --chat <id|@username> --limit 50 --source both --json --timeout 90s
tgcli messages buttons list --chat <id|@username> --id <msgId> --json --timeout 30s
tgcli messages buttons click --chat <id|@username> --id <msgId> --row 1 --column 1 --json --timeout 30s

messages buttons list 始终会读取实时消息，并返回从 1 开始的坐标以及安全的按钮元数据；它绝不会打印回调负载字节。请使用这些确切坐标调用 messages buttons click。该点击命令仅支持回调按钮；对于 URL/Web App 或受密码保护的按钮，会安全地拒绝执行。

此处切勿使用 --since；正确的标志是 --after。

搜索

tgcli messages search "Claude Code" --chat <id|@username> --source archive --json --timeout 30s
tgcli messages search --query "Claude Code" --chat <id|@username> --source archive --json --timeout 30s
tgcli messages search --regex "claude\\s+(code|agent)" --chat <id|@username> --source archive --json --timeout 30s
tgcli messages search --tag ai --chat <id|@username> --source archive --json --timeout 30s
tgcli messages search --tags "ai,dev" --chat <id|@username> --source archive --json --timeout 30s
tgcli messages search "release" --chat <id|@username> --after 2025-06-01T00:00:00Z --before 2025-06-30T00:00:00Z --source archive --json --timeout 30s
tgcli messages search "Release" --case-sensitive --chat <id|@username> --source archive --json --timeout 30s

位置参数查询和 --query 标志均可使用。--chat 接受多个值。使用 --regex 进行模式匹配，使用 --tag/--tags 按频道标签筛选，使用 --after/--before 指定日期范围，使用 --case-sensitive 禁用不区分大小写的搜索。

发送文本/照片/文件

⚠ send 使用 --to（别名 --chat）指定目标；然后使用 --message（别名 --text）传入文本正文，使用 --photo 上传照片，使用 --file 上传通用文件。

对于多行文本，请使用带单引号 here-doc 分隔符的 stdin 辅助命令：

python3 ~/.agents/skills/tgcli/scripts/send_text.py --to <id|@username> <<'TGCLI_MESSAGE'
Первая строка.

1. Первый пункт.
2. Второй пункт.
TGCLI_MESSAGE

引用分隔符可防止 shell 展开，而 stdin 会保留实际换行符。直接使用 tgcli send text --message "..." 仍适用于简短、静态的单行消息。

tgcli send text --to <id|@username> --message "Hello" --json --timeout 30s
tgcli send text --to <id|@username> --topic <topicId> --message "**Hello**" --parse-mode markdown --json --timeout 30s
tgcli send text --to <id|@username> --message "Done" --reply-to <messageId> --json --timeout 30s
tgcli send text --to <id|@username> --message "https://example.com check this" --no-preview --json --timeout 30s
tgcli send text --to <id|@username> --message "Nightly report" --silent --json --timeout 30s
tgcli send text --to <id|@username> --message "Confidential" --no-forwards --json --timeout 30s
tgcli send text --to <id|@username> --message "Good morning!" --schedule "2025-01-15T09:00:00+03:00" --json --timeout 30s
tgcli send text --to <id|@username> --message "Hello" --retries 3 --json --timeout 30s

tgcli send photo --to <id|@username> --photo /path/to/image.png --caption "Report" --json --timeout 30s
tgcli send photo --to <id|@username> --photo /path/to/image.png --caption "**Report**" --parse-mode markdown --json --timeout 30s
tgcli send photo --to <id|@username> --photo /path/to/image.png --reply-to <messageId> --json --timeout 30s
tgcli send photo --to <id|@username> --photo /path/to/image.png --caption "Breaking news" --caption-above --json --timeout 30s
tgcli send photo --to <id|@username> --photo /path/to/image.png --spoiler --json --timeout 30s
tgcli send photo --to <id|@username> --photo /path/to/image.png --retries 3 --retry-backoff exponential --json --timeout 30s

tgcli send file --to <id|@username> --file /path/to/file --caption "Report" --json --timeout 30s
tgcli send file --to <id|@username> --file /path/to/file --caption "<b>Report</b>" --parse-mode html --json --timeout 30s
tgcli send file --to <id|@username> --file /path/to/file --filename custom-name.pdf --json --timeout 30s
tgcli send file --to <id|@username> --file /path/to/file --reply-to <messageId> --json --timeout 30s
tgcli send file --to <id|@username> --file /path/to/file --caption "Breaking news" --caption-above --json --timeout 30s
tgcli send file --to <id|@username> --file /path/to/photo.jpg --spoiler --json --timeout 30s
tgcli send file --to <id|@username> --file /path/to/photo.jpg --force-document --json --timeout 30s

照片预览与文档上传

• 当需要 Telegram 将本地 PNG/JPG 渲染为照片预览时，使用 tgcli send photo。
• 对于通用上传和明确作为文档样式附件的文件，使用 tgcli send file。
• 对于草稿/审批流程，请先发送到已保存消息，在 Telegram 中审核，然后再转发到目标聊天。

媒体下载

tgcli media download --chat <id|@username> --id <msgId> --json --timeout 30s
tgcli media download --chat <id|@username> --id <msgId> --output /path/to/save --json --timeout 30s

频道

tgcli channels list --query "ai" --limit 20 --json --timeout 30s
tgcli channels show --chat <id|@username> --json --timeout 30s
tgcli channels sync --chat <id|@username> --enable --json --timeout 30s
tgcli channels sync --chat <id|@username> --disable --json --timeout 30s

话题

tgcli topics list --chat <id|@username> --limit 50 --json --timeout 30s
tgcli topics search --chat <id|@username> --query "release" --limit 20 --json --timeout 30s

联系人

tgcli contacts search "alex" --limit 20 --json --timeout 30s
tgcli contacts show --user <id> --json --timeout 30s
tgcli contacts alias set --user <id> --alias "Alex" --json --timeout 30s
tgcli contacts alias rm --user <id> --json --timeout 30s
tgcli contacts tags add --user <id> --tag coworker --tag ai --json --timeout 30s
tgcli contacts tags rm --user <id> --tag ai --json --timeout 30s
tgcli contacts notes set --user <id> --notes "Met at meetup" --json --timeout 30s

群组

tgcli groups list --query "dev" --limit 20 --json --timeout 30s
tgcli groups info --chat <id|@username> --json --timeout 30s
tgcli groups requests list --chat <id|@username> --limit 100 --json --timeout 30s
tgcli groups requests list --chat <id|@username> --query "alex" --json --timeout 30s
tgcli groups requests list --chat <id|@username> --link <invite-url> --json --timeout 30s
tgcli groups requests approve --chat <id|@username> --user <userId> --json --timeout 30s
tgcli groups requests decline --chat <id|@username> --user <userId> --json --timeout 30s
tgcli groups rename --chat <id|@username> --name "New Name" --json --timeout 30s
tgcli groups members add --chat <id|@username> --user <userId> --user <userId2> --json --timeout 30s
tgcli groups members remove --chat <id|@username> --user <userId> --json --timeout 30s
tgcli groups invite get --chat <id|@username> --json --timeout 30s
tgcli groups invite edit --chat <id|@username> --link <invite-url> --request-needed true --json --timeout 30s
tgcli groups invite edit --chat <id|@username> --link <invite-url> --request-needed false --json --timeout 30s
tgcli groups invite revoke --chat <id|@username> --json --timeout 30s
tgcli groups join --code <invite-code> --json --timeout 30s
tgcli groups leave --chat <id|@username> --json --timeout 30s

加入请求命令需要群组管理员权限。切勿同时使用 --query 和 --link。仅批准或拒绝最新 groups requests list 结果中返回的确切 userId；其他管理员可能已经处理了该请求。groups invite edit 会原地更改指定的现有链接，绝不会撤销该链接。请传入确切链接，并确认 JSON 响应包含相同的 link 以及所请求的 requestNeeded 值。groups invite get --json 会返回主要链接及其生效的 requestNeeded 和 isPrimary 值，以便回读验证。

标签（频道分类）

tgcli tags list --chat <id|@username> --json --timeout 30s
tgcli tags set --chat <id|@username> --tag ai --tag dev --json --timeout 30s
tgcli tags search --tag ai --limit 20 --json --timeout 30s
tgcli tags auto --limit 50 --json --timeout 90s            # AI-powered: generates tags from channel metadata/content
tgcli tags auto --chat <id|@username> --source manual --json --timeout 90s
tgcli tags auto --limit 50 --no-refresh-metadata --json --timeout 90s

元数据（频道缓存）

tgcli metadata get --chat <id|@username> --json --timeout 30s
tgcli metadata refresh --chat <id|@username> --force --json --timeout 30s
tgcli metadata refresh --only-missing --limit 50 --json --timeout 90s

文件夹

tgcli folders list --json --timeout 30s
tgcli folders show <name|id> --json --timeout 30s
tgcli folders show <name|id> --resolve --json --timeout 30s
tgcli folders create --title "Name" --emoji "🤖" --json --timeout 30s
tgcli folders edit <name|id> --title "New Name" --json --timeout 30s
tgcli folders delete <name|id> --json --timeout 30s
tgcli folders order <id1> <id2> <id3> --json --timeout 30s
tgcli folders add-chat <folder> --chat <id> --json --timeout 30s
tgcli folders remove-chat <folder> --chat <id> --json --timeout 30s
tgcli folders join --link "https://t.me/addlist/slug" --json --timeout 30s

使用 folders show 搭配 --resolve，可将对等方 ID 解析为易读的频道/用户名（速度较慢，每个对等方都需要调用 API）。不使用 --resolve 时，对等方会显示为带类型的 ID（例如 channel:123）。

同步任务

tgcli sync status --json --timeout 30s
tgcli sync jobs list --json --timeout 30s
tgcli sync jobs list --status error --json --timeout 30s
tgcli sync jobs list --channel <id|@username> --json --timeout 30s
tgcli sync jobs add --chat <id|@username> --depth 500 --json --timeout 30s
tgcli sync jobs add --chat <id|@username> --min-date 2025-01-01T00:00:00Z --json --timeout 30s
tgcli sync jobs retry --all-errors --json --timeout 30s
tgcli sync jobs retry --job-id <id> --json --timeout 30s
tgcli sync jobs retry --channel <id|@username> --json --timeout 30s
tgcli sync jobs cancel --job-id <id> --json --timeout 30s
tgcli sync jobs cancel --channel <id|@username> --json --timeout 30s

不要使用 tgcli sync --chat ...；请使用 sync jobs add --chat ... 将工作加入队列，然后通过 tgcli sync --once 或 tgcli sync --follow 处理。

所有者请求结果

tgcli owner request <requestId> --json --timeout 30s

当前所有者会在内存中保留近期请求结果。completed 表示其处理程序已成功完成；failed 表示发生错误，并包含错误代码。running 表示尚未完成。带有代码 UNKNOWN_RESULT 的 unknown 表示取消操作导致结果无法确定；不带代码的 unknown 表示当前所有者没有记录（例如，重启后）。这两种情况都不能证明消息未发送。

服务（后台同步守护进程）

关闭时会取消已接受的所有者请求，并等待清理完成。如果清理卡住超过 10 秒，所属进程会报错退出；随后，操作系统会释放其存储保护锁。实时 MCP 工具有 30 秒的截止时间，并会遵循调用方的取消请求。

tgcli service status --json --timeout 30s
tgcli service install --json --timeout 30s
tgcli service start --json --timeout 30s
tgcli service stop --json --timeout 30s
tgcli service logs --json --timeout 30s

配置与身份验证

tgcli auth --json --timeout 30s
tgcli auth --qr --json --timeout 30s
tgcli auth status --json --timeout 30s
tgcli auth logout --json --timeout 30s
tgcli config list --json --timeout 30s
tgcli config get <key> --json --timeout 30s
tgcli config set <key> <value> --json --timeout 30s
tgcli config unset <key> --json --timeout 30s
# Global fallback shared by all profiles
# ~/.tgclirc: proxy=socks5://127.0.0.1:1080
# Route via SOCKS5 for only the selected profile (stored in config.json)
tgcli config set proxy socks5://127.0.0.1:1080 --json --timeout 30s
# Route via MTProxy (Telegram t.me link format also accepted)
tgcli config set proxy "https://t.me/proxy?server=HOST&port=PORT&secret=SECRET" --json --timeout 30s
# Or via env variable (overrides profile config and ~/.tgclirc):
# export TELEGRAM_PROXY="https://t.me/proxy?server=HOST&port=PORT&secret=SECRET"
# Remove the configured proxy
tgcli config unset proxy --json --timeout 30s
tgcli doctor --json --timeout 30s
tgcli doctor --connect --json --timeout 30s

归档与分析工作流

对于“分析聊天记录”“这周发生了什么”“摘要/新闻”等任务：

1. 解析聊天：
   • tgcli channels list --query "<name>" --json --timeout 30s
   • 可选：tgcli groups list --query "<name>" --json --timeout 30s
2. 确保归档流程已启动：
   • tgcli channels sync --chat <id> --enable
   • tgcli sync jobs add --chat <id> --depth 500
   • tgcli service status --json --timeout 30s — 检查是否正在运行
   • tgcli service install --json --timeout 30s — 如果尚未安装
   • tgcli service start --json --timeout 30s — 启动守护进程
3. 优先读取归档：
   • tgcli messages list --chat <id> --source archive --limit 500 --json --timeout 30s
4. 如果归档仍为空，则回退到实时读取：
   • tgcli messages list --chat <id> --source live --limit 500 --json --timeout 90s
5. 根据 JSON 载荷生成摘要/综合分析。

持续同步工作流

对于“监控这些频道”“持续同步我的订阅”等任务：

架构：channels sync --enable 将频道标记为监控对象 → sync jobs add 创建回填任务 → service start 启动常驻守护进程，处理任务并拉取实时更新。

1. 为每个频道启用同步：
   • tgcli channels sync --chat <id|@username> --enable --json --timeout 30s
   • 对每个要监控的频道重复此操作
2. 添加回填任务（可选，用于拉取历史记录）：
   • tgcli sync jobs add --chat <id|@username> --depth 1000 --json --timeout 30s
3. 启动后台守护进程：
   • tgcli service install --json --timeout 30s — 仅首次需要
   • tgcli service start --json --timeout 30s
4. 验证是否正在运行：
   • tgcli service status --json --timeout 30s
   • tgcli sync status --json --timeout 30s — 显示各频道的同步进度
5. 检查错误：
   • tgcli sync jobs list --status error --json --timeout 30s
   • tgcli sync jobs retry --all-errors --json --timeout 30s
6. 停止监控某个频道：
   • tgcli channels sync --chat <id|@username> --disable --json --timeout 30s

无需 systemd 服务的替代方式（单次运行或前台运行）：

• tgcli sync --once — 执行一次同步并退出
• tgcli sync --follow — 在前台持续同步（按 ctrl-c 停止）
• tgcli sync --follow --idle-exit 5m — 空闲 5 分钟后自动退出

同步语义

• “我的频道/订阅” → tgcli channels list ...
• “受监控/已同步的频道” → tgcli sync status --json --timeout 30s

触发示例

应触发

• “读取 中的消息”
• “在 Telegram 中搜索 ”
• “将这段文字/这个文件发送到 Telegram”
• “从 Telegram 消息中下载文件”
• “总结本周讨论的内容”
• “ 有什么新内容？”
• “显示我在 中收到的提及”
• “按主题为频道添加标签”
• “将用户添加到 Telegram 群组”
• “获取群组邀请链接”
• “回复特定的 Telegram 消息”
• “列出 Telegram 消息上的按钮”
• “点击内联回调按钮”
• “开始同步此频道”
• “监控我的 Telegram 频道”
• “прочитай сообщения в канале”
• “найди в телеграме про релиз”
• “отправь сообщение в канал”
• “дай сводку по чату”
• “скачай файл из сообщения”
• “опубликуй пост с картинкой”
• “отправь фото с подписью в канал”
• “发布带封面图片的帖子”

不应触发

• “编辑/删除/转发 Telegram 消息”
• “用表情符号回应消息”
• “封禁/踢出/提升用户权限并设置细粒度权限”

这些操作请使用 telegram-mcp。