
telegram-search
🔍 导出并模糊搜索 Telegram 聊天记录 | Export and fuzzy search your Telegram chat history
Install with your AI
Paste into Claude Code, Cursor, or any agent — it reads the repo and wires the tool into your project.
Install and set up telegram-search (git-clone project) into my current project. Found on https://claudeers.com/telegram-search Repo: https://github.com/groupultra/telegram-search Homepage/docs: https://search.lingogram.app Detected install method: git-clone → git clone https://github.com/groupultra/telegram-search Category: uncategorized. Platforms: cli, api, web. Read the repo's README for exact setup and env vars, then install it and wire it into my project. Claudeers Health Verdict: unknown; community-verified: false. Confirm the source before running anything.
git clone https://github.com/groupultra/telegram-search
// compatibility
| Platforms | cli, api, web |
|---|---|
| Operating systems | — |
| AI compatibility | claude |
| License | AGPL-3.0 |
| Pricing | open-source |
| Language | TypeScript |

[!TIP] 是否曾因 Telegram 无法搜索中文聊天记录而困扰?
或者想查找一条重要消息,却被海量消息淹没,难以定位?
有了 Telegram Search,您可以备份并检索自己的 Telegram 消息。消息在本地分词后建立索引,中文等不以空格分词的语言也能按词命中。
支持向量搜索,按句子语义模糊匹配。还支持未读消息 AI 摘要、AI 助手对话等功能。
推荐使用
tgsCLI:本地登录一次,就能在终端检索,也可以交给 Claude Code、Codex 等 AI Agent 调用。
💖 赞助者
[!WARNING] 本项目未发行任何虚拟货币,请警惕诈骗。本软件仅供导出和检索个人聊天记录,切勿用于违法用途。
🚀 快速开始:CLI
# 安装(macOS / Linux)。命令为 tgs,旧命令 tg-search 仍可用
brew tap groupultra/telegram-search https://github.com/groupultra/telegram-search
brew install groupultra/telegram-search/tg-search
# 登录(已内置 API ID / Hash,无需到 my.telegram.org 申请)
tgs auth login
# 后台常驻,实时保存新消息(以当前用户运行,不要 sudo)
brew services start groupultra/telegram-search/tg-search
# 同步历史并搜索
tgs chats list
tgs sync --takeout --chat 123456 --from 2026-01-01
tgs search "项目进展"
sync --takeout 如返回 TAKEOUT_AUTHORIZATION_REQUIRED,在其他 Telegram 设备上批准导出请求后重试。
常用命令
| 命令 | 作用 | 连接 Telegram |
|---|---|---|
auth login | 登录 | 是 |
chats list / messages list --chat <id> | 读取会话和消息,不写入本地 | 是 |
sync --takeout --chat <id> / --all | 同步历史到本地 | 是 |
search / context / messages query / stats | 本地检索、上下文、查询、统计 | 否 |
export --from --to --output <dir> | 导出按月 JSONL | 否 |
daemon run / status / stop | 管理 daemon | 是 |
profile inspect / doctor | 检查配置和 daemon 状态 | 否 |
--profile <name> 隔离多个账号,--json 输出 JSON。完整说明见 CLI 文档。
🤖 交给 AI Agent
用户本地 auth login 一次后,Agent 即可用 --json 调用命令:stdout 只有结构化结果,日志和进度写入 stderr。可直接加载仓库内的 Agent skill。
Agent 只有在用户同意后才能使用 sync --takeout。
自定义 API 凭据(可选)
tgs profile configure --apiId YOUR_API_ID --apiHash YOUR_API_HASH # 写入 profile
export TELEGRAM_API_ID=YOUR_API_ID TELEGRAM_API_HASH=YOUR_API_HASH # 或用环境变量
两项须成对提供,profile 优先。不带参数运行 profile configure 恢复内置凭据。
远程只读模式
export TG_SEARCH_REMOTE_TOKEN=...
tgs --profile cloud profile remote https://tgs.example.com
tgs --profile cloud search "项目进展"
从源码构建
pnpm install && pnpm run build:packages && pnpm -F @tg-search/cli build
pnpm cli auth login
✅ 功能
- Takeout 批量同步历史,daemon 实时保存新消息、编辑和删除
- 分词检索;服务端另支持向量语义检索和以文搜图
- 按月 JSONL 导出,附 SHA-256 校验清单
- RAG 问答、未读消息 AI 汇总
- Telegram Bot 搜索与导出
- 服务端媒体可备份至 MinIO
🛣️ 路线展望
- 自动生成会话总结
- 「超级大脑」:根据历史消息构建人物与事件的知识图谱
- 自动整理「已保存消息」
- 链接与图片索引:网页摘要、OCR、图片描述
- 支持 Discord 等其他平台
🖥️ 网页界面(可选)
在线体验:search.lingogram.app。自行部署:
mkdir telegram-search && cd telegram-search
curl -L https://raw.githubusercontent.com/groupultra/telegram-search/refs/heads/main/docker/docker-compose.yml -o docker-compose.yml
curl -L https://raw.githubusercontent.com/groupultra/telegram-search/refs/heads/main/docker/.env.example -o .env
curl -L https://raw.githubusercontent.com/groupultra/telegram-search/refs/heads/main/docker/init.sql -o init.sql
docker compose -f docker-compose.yml up -d
然后打开 localhost:3333。也可以只运行镜像(未配置 MinIO 时媒体存于 data/media):
docker run -d -p 3333:3333 ghcr.io/groupultra/telegram-search:latest
环境变量
均为可选。AI Embedding / LLM 在应用内按账户配置(设置 → API)。
| 环境变量 | 说明 | 示例值 |
|---|---|---|
TELEGRAM_API_ID | 自定义 Telegram 应用 ID,不填则使用内置凭据 | 611335 |
TELEGRAM_API_HASH | 自定义 Telegram 应用 Hash,需与 ID 成对填写 | d524b414d21f4d37f08684c1df41ac9c |
DATABASE_TYPE | 数据库类型,可选 postgres 或 pglite | pglite |
DATABASE_URL | PostgreSQL 连接字符串(仅在 DATABASE_TYPE=postgres 时填写) | postgresql://postgres:123456@pgvector:5432/postgres |
TELEGRAM_BOT_TOKEN | 通过 @BotFather 创建的 Telegram Bot Token | 123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11 |
PROXY_URL | 代理地址(支持如 socks5://user:pass@host:port 等格式) | socks5://user:pass@host:port |
PORT | 后端服务 HTTP/WebSocket 监听端口 | 3333 |
HOST | 后端服务监听地址 | 0.0.0.0 |
BACKEND_URL | Nginx 作为反向代理时用于 /api 和 /ws 的上游后端地址 | http://127.0.0.1:3333 |
MINIO_URL | MinIO 服务地址 | http://minio:9000 |
MINIO_ACCESS_KEY | MinIO 访问密钥 | minioadmin |
MINIO_SECRET_KEY | MinIO 访问密钥对应的密钥 | minioadmin |
MINIO_BUCKET | MinIO 存储桶名称 | telegram-media |
💻 开发指南
pnpm install && cp .env.example .env
pnpm run dev # 纯浏览器模式
docker compose -f docker/docker-compose.dev.yml up -d pgvector minio
pnpm run server:dev # 服务器模式,另开终端运行 web:dev
pnpm run web:dev
更多见 CONTRIBUTING.md。
🚀 Activity
// faq
What is telegram-search?
🔍 导出并模糊搜索 Telegram 聊天记录 | Export and fuzzy search your Telegram chat history. It is open-source on GitHub.
Is telegram-search free to use?
telegram-search is open-source under the AGPL-3.0 license, so it is free to use.
What category does telegram-search belong to?
telegram-search is listed under uncategorized in the Claudeers registry of Claude-compatible tools.
// embed badge
[](https://claudeers.com/telegram-search)
// retro hit counter
[](https://claudeers.com/telegram-search)
// reviews
// guestbook
// related in Uncategorized / Others
Reverse engineer anything with agents, from app behavior down to native binaries.
Fair-code workflow automation platform with native AI capabilities. Combine visual building with custom code, self-host or cloud, 400+ integrations.
The agent engineering platform.
100+ AI Agent & RAG apps you can actually run — clone, customize, ship.
// built by
2 of its contributors also build on official projects — claude-cookbooks, claude-quickstarts, typescript-sdk
→ see how telegram-search connects across the ecosystem