WireCat Telegram

tg — 面向 AI Agent 的 Telegram 命令行工具

在终端中使用完整的 Telegram 账号，在电脑上搜索，并可供 Claude Code、 Codex、Cursor 或任何 Agent 使用——范围由你设定。

文档 · 示例 · WireCat

对话示例（人物为虚构，输出仅供说明）：

You:    Use tg CLI. What did I promise anyone in the last three days?
Agent:  (runs tg personal review 'date>3d': 12 chats)
        I owe
        · Alice Example — the invoice by Friday. "Alice Example", 24.09
        Waiting on others
        · Bob Sample — the mock-up by 25.09. Not in "Design" yet
You:    Remind Bob about the mock-up.
Agent:  Draft: "Hi Bob, how is the mock-up going?" Send it?
You:    Yes.

快速开始

npm install -g @wirecat/tg-cli    # or: bun add -g @wirecat/tg-cli; pnpm: see docs/installation.md
tg skill install --for all        # the agent skill, for Claude Code, Codex and Gemini CLI
tg personal setup                 # app registration and login
tg personal inbox                 # other people's unread messages, in every chat; nothing is marked read

全局安装不会安装 Agent 技能：运行 tg personal setup 可安装该技能，也可以运行 tg skill install --for all。npm 可能会警告安装脚本被阻止，或“尚未纳入 allowScripts 白名单”（@wirecat/tg-cli、 better-sqlite3）；这不会造成影响，你无需允许这些脚本——了解原因。 在 Windows 上，如果找不到 tg，请打开新的终端，或使用 安装指南中的 PowerShell 安装程序。

预留约 5 分钟。tg personal setup 会在 my.telegram.org 注册你自己的 Telegram 应用，通过二维码登录，检查你的首批聊天，并安装 Agent 技能。下载较早的历史记录需要单独执行。

需要在 macOS、Linux 或 Windows 上运行 Node 22.19+ 或 24+，或使用 Bun。无需安装即可试用： npx @wirecat/tg-cli --help。

更多信息：安装指南 · wirecat.dev 上的文档

可以用它做什么？

快速了解近况。 “使用 tg CLI。今天上午以来有哪些新消息？谁还在等我回复？”

tg personal inbox
tg personal review 'date>1d'

查找任何内容。 “使用 tg CLI。我们什么时候和 Alice 确定了场地？”——获取包含日期和消息原文的答案。

tg personal search all "venue"                # messages and notes on this computer, and Telegram's own search

默认情况下，这些词也会发送到 Telegram 服务端进行搜索；添加 --offline 可让查询仅在这台电脑上进行。

信守承诺。 “使用 tg CLI。我答应过什么？还有什么事在等我处理？” tg personal review 会在一次调用中汇总上次检查以来的所有发言，也包括你自己的消息。

tg personal review --new                      # what changed since the last review --new

管理群组。 “使用 tg CLI。Hiking 群里哪些问题还没人回答？”

tg personal review chat:Hiking --unanswered
tg personal chats events "Hiking" "time>=7d"  # who joined, left, was added or removed

更多内容：实用示例，每个示例均设有计划和限制 · wirecat.dev 上的文档

为 AI Agent 打造

你的 Agent。你的 Telegram。你的规则。

• 配备终端的 Agent（例如 Claude Code、Codex、Gemini CLI）会自行运行 tg 命令。随附的 技能 会告诉它们如何操作：运行 tg personal setup --agent … 或 tg skill install 即可完成设置，登录前运行 tg skill show 可显示技能内容。
• 没有终端的应用（例如 Claude Desktop、Cursor 和其他 MCP 客户端）可连接到 tg personal mcp serve。它内置了可直接使用的提示词：/catch-up、/review、/reply、/find、/open-tasks 和 /link-conversations。

tg personal mcp add claude-code  # or: tg personal mcp add codex
tg personal mcp config      # the entry for Claude Desktop, Cursor and others

该配置文件默认允许发送消息，因此 mcp add 会先停止。检查配置文件的权限，然后使用 --allow-writes 再次运行。

更多信息：MCP 服务 · wirecat.dev 上的介绍

为什么选择 tg？

• 访问你的整个账号，而不只是机器人。 每个聊天、群组、频道和联系人，以及它们的历史记录——tg 就像你的又一台设备。
• 本地优先搜索。 所有读取的内容都会保存在你的电脑上。搜索会读取这份副本，默认情况下还会搜索 Telegram 自带的搜索；使用 --offline 可让查询仅在你的电脑上进行。
• 为 Agent 打造。 每次调用只执行一项操作；使用 --json 时，JSON 格式始终一致；每种失败都有固定的退出代码；还提供 MCP 服务和技能。
• 默认安全。 读取不会将任何内容标记为已读。配置文件决定 Agent 可以执行哪些操作、可以向哪些聊天发送消息，以及每小时可发送多少条消息（默认 30 条）。如果发送结果未知，tg 会明确说明，并提供一个可重复执行的命令，Telegram 不会因此重复投递消息。
• 也支持完整的 Bot API。 提供全部 185 个方法，以及便捷的机器人命令。

更多信息：与其他工具的比较 · wirecat.dev 上的介绍

你的账号

tg 以你的名义运行，就像你的又一台设备。它不是机器人：它通过 MTProto（Telegram 为客户端应用提供的 API）与 Telegram 通信，使用的是你自行注册的应用。它可以访问你的聊天及其历史记录、群组、频道和联系人。

tg personal chats list --limit 5
tg personal messages list "Book club" --limit 20
tg personal messages send "Book club" "Call at 3?" --reply-to <id>
tg personal reactions add "Book club" <id> 👍
tg personal messages send me "Call mum" --at-time 2h  # a reminder in Saved Messages in two hours
tg personal messages send "Book club" "The minutes" --file minutes.pdf
tg personal messages download "Book club" <id> --output-dir ~/Downloads
tg personal messages transcribe "Book club" <id>  # a voice message as text

• 读取。 聊天、历史记录、带有前后消息的单条消息、每个聊天中其他人的未读消息（tg personal inbox）、上次查看之后的所有内容（tg personal review）、新消息到达时实时查看（tg personal watch）、消息文件，以及将语音消息转成文本。
• 发送。 Markdown、回复、文件、照片、视频和语音消息；静默消息和定时消息（即使这台电脑关机，消息也会发出）；编辑、转发、置顶、回应、投票、删除——可仅对你生效，也可对所有人生效。
• 在你的电脑上处理语音。 Telegram 会为 Premium 账号转录语音；tg 也可以在这台机器上运行语音模型，只会在你提出请求时下载。
• 联系人和账号。 添加、重命名、屏蔽和导入联系人；为他人设置你自己的别名和备注；查看当前登录身份，以及所有已登录该账号的设备。
• 单个联系人。 查看其个人资料、上次在线时间、你们共同聊天中的消息，以及该账号是否像机器人或垃圾信息发送者。

更多信息：使用 tg · wirecat.dev 上的介绍 · 单个联系人 · wirecat.dev 上的介绍

登录和配置

每位用户都会注册自己的 Telegram 应用；tg personal setup 或 tg personal session start 会替你完成。应用密钥会存入系统密钥环，会话文件则只有你自己的用户才能读取。

tg personal session start               # a QR code: Settings → Devices → Link Desktop Device
tg personal session start phone         # or a phone number, the code and your 2FA password
tg personal session start qr            # without a terminal (an agent): the QR code as text to paste into the chat
tg personal account show                # who you are logged in as
tg account list                         # every profile here, and who each is logged in as

多个账号对应多个配置，而配置名称是第一个词，不是选项：

tg personal chats list     # profile "personal"
tg work chats list         # profile "work"
export TG_PROFILE=work     # or for the whole shell session

tg 绝不会替你选择配置，即使只有一个也不例外：使用账号但未指定配置名称的命令会停止运行，并列出这台计算机上的配置。请指定一个配置，或为整个 Shell 会话设置 TG_PROFILE。

更多信息：登录和会话 · wirecat.dev 上的文档 · 配置 · wirecat.dev 上的文档

本地存储和搜索

tg 读取的所有内容都保存在你计算机上的本地存储中。默认情况下，搜索会同时搜索本地存储和 Telegram；--offline 则只从本地存储中搜索，不建立连接。

tg personal search messages 'contract chat:"Project Alpha"'
tg personal search messages "contract" --backend archive  # local only
tg personal messages sync "Project Alpha" --last 5000 --background
tg personal store export "Project Alpha" --format markdown --output alpha.md
tg personal messages evidence "Project Alpha" --json  # bounded evidence for a chat brief
tg personal server install                         # keep the store current as a systemd or launchd service
tg personal store backup ~/tg-backup.db            # a copy, safe while the store is in use

按文字、人物、日期、文件、链接和标签搜索；保存搜索；按主题查找讨论。

更多信息：搜索 · wirecat.dev 上的文档 · 本地存储 · wirecat.dev 上的文档

你管理的群组

tg personal review chat:Hiking --unanswered   # questions nobody answered in 24 hours
tg personal chats events "Hiking" "time>=7d"  # who joined, left, was added or removed, and by whom
tg personal chats members list "Hiking" --all     # everyone, with their role and when they were last seen
tg personal topics list "Hiking"                  # a forum group's topics, newest activity first
tg personal chats inspect https://t.me/+AbCdEf    # where an invite link leads, without joining
tg personal chats create "Hiking 2027" @alice_example  # a new group, with the people you name
tg personal stats chats show "Hiking"             # group activity

重命名群组、添加和移除成员及管理员、处理加入请求和邀请链接、管理论坛主题，以及设置链接、转发和刷屏的审核规则，也都可以通过命令完成。

更多信息：你管理的群组 · wirecat.dev 上的文档

机器人

tg personal bot 通过 Telegram 官方 Bot API 和来自 @BotFather 的令牌与机器人交互。你可以使用多个机器人；每个机器人都有一个由你选择的名称，该名称就是命令的第一个词。

tg sales bot auth set                    # the token, at a hidden prompt; Telegram checks it first
tg sales bot auth show                   # which bot it is
tg sales bot recipients add user:<id>    # the bot may write only here
tg sales bot messages send "Team" "Build is ready" --file report.pdf
tg sales bot api --help                  # every Bot API method, each with its fields
tg personal bot list --check             # every bot on this computer

• 所有 Bot API 方法。 tg <bot> bot api <method> 接受原生字段标志或 JSON 请求体。
• 每个名称对应一个令牌，存放在密钥环中，与你自己的登录分开；CI 可使用 TG_BOT_TOKEN。令牌绝不会被打印出来——错误信息、--trace 输出和运行记录中都不会出现。
• 接收对象和日志。 每个机器人都有自己的可发送消息的聊天列表，以及一份不含文本的操作日志。
• 消息、管理员、成员、按钮、菜单、Webhook——发送、编辑、删除和置顶；使用 bot chats admins、bot callbacks answer、bot commands、bot webhooks。
• 历史记录。 bot watch 会显示并保存机器人聊天中的动态；bot messages sync 会导入较早的频道和超级群组消息。

更多信息：Telegram 机器人 · wirecat.dev 上的文档

Agent 设置详情

技能。 Claude Code 会读取 ~/.claude/skills/tg-cli/；Codex、Gemini CLI 和本地 Cursor 会读取 ~/.agents/skills/tg-cli/。如果新 Agent 会话未识别到该技能，请启动一个新会话。

tg skill install --for all        # both folders, without logging in
tg skill show                     # the complete instructions, without installing them

MCP 服务。 命令及其参数和当前可用状态始终可供发现。配置中的 permissions 决定哪些命令可以运行。readonly 会禁止写入；设为 ask 时，服务不会显示表单，因此请在你的 Agent 应用中设置审批。

claude mcp add tg -- tg personal mcp serve  # Claude Code, by hand
tg personal mcp check            # check the local MCP server

通过浏览器访问。 使用终端中的一次性访问码登录后，浏览器中的 ChatGPT 或 Claude 即可通过隧道访问 tg personal mcp serve --http --public-url <url>。

更多信息：MCP 服务 · wirecat.dev 上的文档 · 远程访问 · wirecat.dev 上的文档

面向脚本和 Agent 的输出

使用 --json 时，命令只输出数据，作为一个 JSON 值——没有表格、颜色或提示；其他程序读取其输出时也是如此。--jsonl 每行输出一个对象。所有列表的结构都相同：

{ "items": [ … ], "page": { "limit": 20, "has_more": true }, "meta": { … } }

错误会作为一行内容写入 stderr，stdout 为空，命令以固定代码退出：4 表示登录，5 表示该配置不得执行此操作，6 表示未找到聊天或消息，8 表示达到限制，9 表示 Telegram 未及时响应，14 表示无法确定消息是否已发送。tg commands --json 会输出完整的命令树。部分读取或下载可能以 0 退出：请检查 JSON 中的 complete。

更多信息：CLI 契约 · wirecat.dev 上的文档 · 所有命令和退出代码 · wirecat.dev 上的文档

设置和权限

tg personal config set permissions.messages readonly  # no change to messages from this profile
tg personal config set permissions.messages.send ask  # a question in the terminal before each send
tg personal config set sends_per_hour 10              # at most 10 sends an hour (30 by default)
tg personal recipients add "Book club"                # the first add turns the recipient list on
tg personal sends list                                # every attempt: sent, refused, failed or not known
tg personal config show                               # what is set, and where it came from

更多信息：权限 · wirecat.dev 上的文档 · 配置 · wirecat.dev 上的文档

限制

每个配置都有一个请求频率，所有命令、后台任务和服务同时共享此频率，因此批量操作不会超出 Telegram 的限制。Telegram 的短暂等待会自动等待；如果等待时间较长，则会停止运行，而不会重复尝试。

更多信息：限制和等待 · wirecat.dev 上的文档

安全性

• 会话文件的敏感程度不亚于密码，仅对你的用户可读；应用密钥保存在系统密钥环中。没有任何命令会将密码、登录验证码或电话号码作为参数。
• 本地存储中以未加密形式保存已读取内容的完整文本，仅对你的用户可读。注销后内容仍会保留；只有整盘加密才能防止磁盘被盗后数据泄露。
• 每次发送操作，无论通过命令还是 MCP 执行，都会遵守配置的限制，并写入日志——但不包含消息文本。--file 会拒绝凭据文件、CLI 文件夹和本地存储。
• 名称、标题和消息中的控制字符会以文本形式显示，因此他人的文本无法控制你的终端。
• 这些限制可以防止 Agent 因读到的消息而被诱导发送内容，但无法阻止主动试图绕过限制的 Agent：对此，请在沙盒中或以独立用户身份运行 Agent。

如需报告漏洞：SECURITY.md。

更多信息：安全性 · wirecat.dev 上的文档

遇到问题时

tg personal doctor         # where the files are and whether a session is saved, without connecting
tg personal doctor --online  # check that the login works
tg personal chats list --trace  # each request to Telegram, with no text, names, phone numbers or keys
tg personal runs list      # recorded runs

更多信息：按症状查找故障排除方法 · wirecat.dev 上的文档 · 诊断 · wirecat.dev 上的文档

与其他工具的区别

Telegram 自家的应用是为个人用户打造的；tg 则是为脚本和 Agent 打造的。Telegram 机器人只能看到自己加入的聊天，并以机器人身份发言；tg 则是以你的身份参与自己的聊天。其他开源工具也能将 Telegram 账号连接到 Agent：tgcli、telegram-mcp 和 tdl。

更多信息：与其他工具对比 · wirecat.dev 上的文档

WireCat 的一部分

WireCat 是一个面向 AI Agent 的开源、本地优先上下文层。tg 是它的起点；max-cli 可将 MAX Messenger 接入同一个本地存储。从 Telegram 开始。需要时再添加更多上下文。你的上下文，适用于任何 Agent。

技术文档

每个页面都位于 wirecat.dev/en/docs/tg，也可以在 docs/ 中找到：

页面	内容
索引 · 网页	文档站的起始页：tg 是什么、快速入门，以及接下来可以了解什么
安装 · 网页	如何安装、需要什么、文件存放在哪里，以及如何升级或卸载？
使用 · 网页	如何登录、阅读、翻页、发送消息，以及按此顺序在脚本中使用？
会话 · 网页	登录如何运作：二维码或手机号、my.telegram.org 上的应用、密钥环、配置文件和退出登录？
归档 · 网页	本地存储会保存什么、如何填充、搜索、导出、保持最新并备份？
搜索 · 网页	如何按文字、发送者、聊天、日期、文件、链接或标签查找消息、保存搜索并统计数量？
附件 · 网页	发送、下载和读取文件；提取文档和图片中的文字并进行搜索
排名 · 网页	消息和作者排名：指标、分数、已保存的查询和依据
主题搜索 · 网页	如何按讨论主题查找讨论、保持结果最新，以及哪些内容会离开你的电脑？
查询语言 · 网页	每个搜索字段、运算符、预设、限制和 JSON 答案
群组 · 网页	如何跟进自己管理的群组：未解决问题、新成员、每周报告？
人员 · 网页	关于某个人：个人资料、他们在各个聊天中说过什么，以及账号是否像机器人
机器人 · 网页	通过 Bot API 使用机器人：令牌、接收者、消息、管理员和所有 Bot API 方法
回复 · 网页	按照你的规则回复消息，面向所有人或仅面向你选择的人
MCP · 网页	如何在无需终端的情况下连接 Claude Desktop、Cursor 或其他客户端？
远程 · 网页	通过登录代理和隧道，在浏览器中使用 ChatGPT 或 Claude
方案 · 网页	Agent 每天能为我做什么，以及如何安排定时运行？
比较 · 网页	tg 与 tgcli、telegram-mcp 和 tdl 相比如何，什么情况下其他工具更合适？
命令 · 网页	每个命令、选项和退出代码——由程序生成
配置 · 网页	如何配置常见行为？
权限 · 网页	配置文件可以读取什么、哪些操作会先询问，以及哪些操作可以直接进行
配置文件 · 网页	如何在一台电脑上使用多个账号和机器人，以及命令如何选择其中一个
配置参考 · 网页	每个键、类型、默认值、作用域和变量
CLI 契约 · 网页	调用方式、输出、错误、无头运行、边界和预览
限制 · 网页	限制、等待和后台任务
诊断 · 网页	命令执行了什么，以及哪些内容绝不会被记录？
故障排除 · 网页	遇到问题：屏幕上显示什么，以及该怎么做
安全 · 网页	什么内容会写入磁盘、什么内容绝不会写入，以及如何防止消息发送到错误位置？
路线图 · 网页	接下来会推出什么？
各版本的变更：CHANGELOG.md。

开发

pnpm install
pnpm lint && pnpm typecheck && pnpm test
pnpm build && pnpm smoke:node # the built command, the bundle a user installs
pnpm build && pnpm smoke:bun  # the same under Bun
pnpm generate                 # rewrites docs/commands.md from the command tree
bin/tg session start          # everything under .tg/ in this checkout, never the real profile

所有与 Telegram 无关的内容——命令、存储、发送保护机制、MCP 服务——都位于 cli-core 中，并与 max-cli 共用。Telegram 专属代码仅位于 src/telegram/。

更多信息：ARCHITECTURE · TESTING

贡献

欢迎通过 issues 提交拉取请求、错误报告和想法。

使用 Telegram、其他即时通讯工具和 AI Agent 实现自定义自动化：[email protected]。

许可证

Apache License 2.0 — 请参阅 LICENSE。