Telegram Account Orchestrator (TAO)

Telegram 分享建议使用固定预览入口：https://soulknight666.github.io/telegram-account-orchestrator/

Self-hosted Telegram multi-account management with Web UI, CLI, Bot, MCP, Telethon, and Telegram Desktop tdata import.

TAO is a Telegram account manager and orchestration toolkit for encrypted session storage, account health checks, controlled batch operations, device-session management, account-package processing, and automation through REST or MCP.

• Interfaces: Web UI, REST API, CLI, Telegram Bot, MCP

• Core: Telethon, FastAPI, encrypted SQLite-backed account storage

• Import: StringSession, .session, Telegram Desktop tdata

• License: MIT; GAFBot-derived code is documented in NOTICE.GAFBot and docs/THIRD_PARTY.md

中文说明

Telegram 账号管理器（自托管）

基于 Telethon(MTProto) 的多账号管理工具：加密保存会话、按账号绑定代理与设备指纹、健康检查、受控批量操作、审计日志。CLI + Web 控制台 + AI/Agent 控制层三入口。

Windows 提示「无法验证发布者」：从网上下载的 .bat 没有数字签名时的正常现象，点「运行」即可。也可先运行同目录 unblock.bat，或右键 start.bat → 属性 → 「解除锁定」。

Related MCP server: mcp-telegram

ZIP 工具（网页）

网页控制台「ZIP 工具」面板支持：

转 API 相关环境变量：TAM_TOAPI_BASE（优先）、DM、SERVER_IP/API_PORT。

机器人侧同名能力见菜单「转 API」；号包引擎来自 GAFBot（MIT，见 NOTICE.GAFBot）。

致谢与第三方许可

机器人侧号包处理（tam/gaf/：筛活、转 API、拆包、防找回、整合等）移植自 GAFBot（作者 kugua311 / @kugua332334554）， 采用 MIT License。完整版权声明与许可证原文见本仓库 NOTICE.GAFBot。

按 MIT 条款：再分发时须保留上述版权与许可声明；本项目对 GAFBot 的修改与网页端适配由本仓库维护，与原作者无关。

快速开始

一键启动（推荐，新手选这个）

• Windows：双击 start.bat

• macOS / Linux：./start.sh

• 或：python setup.py --auto

自动完成：检查 Python → 建 .venv → 装依赖（失败自动换清华镜像）→ 生成 .env 与主密钥 → 体检修复 → 按你的选择启动。

启动前只问两件事（写入 .env，下次会记住默认值）：

1. 部署在哪里？ local 自己电脑（只监听 127.0.0.1）/ server 服务器（0.0.0.0，建议令牌+HTTPS）

2. 用哪个前端？ web 网页控制台 / bot Telegram 机器人 / both 两个一起

也可以不进菜单，直接指定：

./start.sh --deploy local --frontend web
./start.sh --deploy server --frontend both --token

• 本机 + 网页：默认免令牌，浏览器打开即用。

• 服务器：默认启用访问令牌。

• 选了机器人但还没有 Token：会提示填一次 @BotFather 的 TAM_BOT_TOKEN（可回车跳过，稍后写 .env）。

• api_id / 代理：一键模式不打断，需要时再写 .env 或网页参数面板（含批量并行 / 单号超时自动跳过 / 重生并行）。

• 其它：--no-start、--port 8848、--skip-install、--no-venv。

手动安装

pip install -r requirements.txt
cp .env.example .env
python -m tam.cli init-key        # 生成 TAM_MASTER_KEY，写入 .env
# 在 my.telegram.org 申请 api_id / api_hash，填入 .env

python -m tam.cli add 主号 --phone +8613800138000 --proxy socks5://127.0.0.1:1080
python -m tam.cli login 1         # 验证码 + 两步验证密码
python -m tam.cli check           # 全部账号健康检查
python -m tam.cli serve           # http://127.0.0.1:8848 Web 控制台

一键体检（出任何问题先跑它）

python -m tam.cli doctor        # 只体检，不改任何东西
python -m tam.cli doctor --fix  # 体检并自动修复
python -m tam.cli doctor --json # 机器可读输出（给脚本 / Agent）

也可以在 Web 控制台右上角点“一键体检”按钮（等价于 doctor --fix）。 安装向导的第 5 步、以及 serve 启动前都会自动跑一遍（serve --no-doctor 可关闭）。

检查 13 项，带 ✓ 的都能自动修：

卡商初始账号批量导入

支持 手机号|取码链接 行格式，例：

+10000000000|https://example.invalid/code/primary/GetHTML
+10000000001|https://example.invalid/code/secondary/GetHTML|美国号B

python -m tam.cli import-accounts accounts.txt --tags batch1 --dry-run   # 先预览
python -m tam.cli import-accounts accounts.txt --tags batch1
cat accounts.txt | python -m tam.cli import-accounts -                   # 也可走 stdin

python -m tam.cli auto-login --id 1            # 发码 → 自动拉取码 → 登录
python -m tam.cli auto-login --tag batch1      # 批量（默认串行 + 随机间隔）

容错与行为：

• 分隔符支持 |、\|、｜、制表符、逗号、分号；两段顺序可以颠倒；手机号缺 + 自动补。

• 第三段作为备注/别名；# 开头与空行忽略；单行出错不中断整批，错误行集中返回。

• 幂等：手机号已存在只补写取码链接，不重复建号。

• 取码：codefetch.py 只用标准库拉取该链接（支持代理），先记录发码前的旧码作基线，再轮询直到出现不同的新码（默认 120s 超时、5s 一次），避免拿错上一次的验证码。

• 旧库自动迁移：启动时缺 code_url 列则自动补列。

• 开了两步验证的号需传 --password（取码链接只能拿到短信码）。

导入 .session / StringSession

卡商号包常见形态是 Telethon 的 .session（SQLite）或 StringSession 字符串。Web 控制台点 「session 导入」，或用 CLI：

# 目录里一批 .session（默认递归）
python -m tam.cli import-sessions /path/to/sessions --tags batch --proxy socks5://127.0.0.1:1080
python -m tam.cli import-sessions /path/to/one.session --label 主号

# 文本文件，一行一个 StringSession；可用 别名|session
python -m tam.cli import-session-strings sessions.txt --tags ss
cat sessions.txt | python -m tam.cli import-session-strings -

行为：

• 转 StringSession → 联网验证可用 → Fernet 加密入库；失效条目不留垃圾行。

• 已存在相同 user_id 则合并更新会话，不重复建号。

• 该能力只走人工入口（Web / CLI），不向 Agent 开放。

• Web 支持三种方式：本机上传 .session/zip、服务端路径、粘贴 StringSession。

API：POST /api/accounts/import-sessions、POST /api/accounts/import-session-strings、POST /api/accounts/import-session-upload。

从 Telegram Desktop tdata 导入

tdata 是桌面端的本地加密目录（key_datas + D877F783D5D3EF8C* 分片），内含 auth_key / dc_id。 解析由内置纯 Python 解析器完成，无需 opentele；兼容 Telegram Desktop 6.x。

python -m tam.cli import-tdata /path/to/tdata --label 主号 --proxy socks5://127.0.0.1:1080
python -m tam.cli import-tdata /path/to/tdata --password 本地密码        # 桌面端设了 passcode
python -m tam.cli import-tdata /path/to/号包目录 --scan --tags tdata   # 批量扫描子目录

行为：

• 转换链路：tdata → StringSession → 连接验证可用 → Fernet 加密入库；全程不落明文 .session 文件。

• 一份 tdata 含多个账号时逐个导入，别名自动加后缀；已有相同 user_id 则合并更新，不重复建号。

• 会话失效的条目不会在库里留垃圾行，错误单独回报。

• 默认使用桌面端官方 API 指纹 + UseCurrentSession（复用原授权，不额外产生新登录记录）；加 --own-api 才改用自己的 API ID，风控更高，不推荐。

• 导入后桌面端仍在线，两端共用同一授权；避免两边同时高频操作。

• 该能力归入 HUMAN_ONLY，不向 Agent 开放，只能人工走 CLI。

架构

tam/
├── config.py     环境配置（.env）
├── crypto.py     scrypt + Fernet：session 静态加密
├── db.py         SQLite：accounts / audit_log（含 code_url 取码链接）
├── importer.py   批量解析导入 手机号|取码链接 清单
├── codefetch.py  从取码链接抽取登录验证码（标准库，支持代理与轮询）
├── tdata.py / tdata_native.py   tdata 扫描与内置解析（无需 opentele）
├── ratelimit.py  令牌桶限速 + 人性化随机延迟
├── manager.py    Telethon 封装：登录、会话上下文、健康检查、批量调度
├── tools.py      AI 控制层：带 JSON Schema 的工具注册表 + 统一调用与安全策略
├── mcp_server.py MCP stdio 服务端（零依赖，供 Claude/Cursor 等接入）
├── api.py        FastAPI REST + Web 控制台
├── cli.py        命令行
└── web/index.html 单页控制台

关键设计

REST 接口

所有 /api/* 需 Authorization: Bearer <TAM_WEB_TOKEN>。若向导里选了“本机免令牌”（TAM_NO_AUTH=1 且 TAM_WEB_TOKEN 为空），则不需要任何头部，直接访问即可。

给 AI / Agent 的控制手段

Agent 可调用能力注册在 tam/tools.py（@tool）。网页「工具箱」另有一份注册表 tam/toolbox.py。

增删工具时两边要同步： 只改 toolbox.py 则仅网页可用；只改 tools.py 则仅 AI/MCP 可用。需要对 AI 隐藏的能力不要写入 tools.py（或列入 HUMAN_ONLY）。详见 FOR_AI.md §8–§9。

MCP 客户端配置示例：

{"mcpServers": {"tam": {"command": "python", "args": ["-m", "tam.mcp_server"], "cwd": "/path/to/tam"}}}

工具清单（danger 标注风险等级）：

登录满 24 小时自动踢出其它设备

• TAM_AUTO_KICK_HOURS=24 全局开关（0 = 关闭）；账号级开关是 auto_kick 字段（Web 抽屉里的“自动清设备”勾选框）。

• 计时起点是 本机接管时间 adopted_at（导入 tdata / StringSession / 验证码登录拿到会话那一刻），不是服务端的会话创建时间。

• 踢完会回拉一次会话列表校验：只有确认“只剩本机”才算成功并重新起算周期；还剩会话或报错则排一个重试。

• TAM_KICK_RETRY=1h 失败后的重试间隔，支持秒/分/时写法：45s、10m、2h、1h30m，纯数字按秒，最小 10 秒。 也可以在 Web 顶栏“失败重试”输入框里改（存在数据库 settings 表，优先于 .env；留空保存即恢复默认）， 或调 POST /api/autokick/retry {"value":"10m"}；POST /api/autokick/run {"retry":"30s"} 只对本轮生效。

• 服务启动后后台每 10 分钟扫一轮；计时基准 = kick_retry_at > last_kick_at > adopted_at > login_at > created_at，满 N 小时就调一次“踢掉其他设备”，并写 auto_kick 审计日志。

• 为什么是 24 小时：Telegram 对新会话有 24 小时保护期，期内新会话无权注销其它会话，提前调只会报错。

• banned / unauthorized / frozen / spam_block_perm 的号自动跳过；失败不再把周期推满一天，而是按 TAM_KICK_RETRY 排重试（默认 1 小时）。

• 手动跑一轮：Web 顶部“立即执行”按钮，或 POST /api/autokick/run。

约定：

• 统一返回 {"ok": bool, "tool": str, "result" | "error": {...}}，工具调用从不抛异常，错误码固定为 unknown_tool / bad_request / not_found / conflict / forbidden / readonly / error。

• destructive 工具不传 confirm: true 时只返回预览（executed: false），不产生任何对外副作用。

• 参数用 JSON Schema 校验，未知参数与缺失必填参数直接拒绝，避免模型幻觉参数静默生效。

• TAM_READONLY=1 或使用 TAM_READONLY_TOKEN 时，写入类工具从清单中消失并被拒绝——推荐给 Agent 单独发只读令牌。

• TAM_DRY_RUN=1 全局干跑；TAM_PEER_ALLOWLIST 限定可发送对象。

• 登录、导入/导出会话不对 Agent 开放，只能人工走 CLI/Web，防止凭证被模型读走。

• CLI 全面非交互化：login --send-code / --code / --password / --non-interactive，list --json，失败退出码非零。

自检：for f in tests/test_*.py; do python3 "$f" || break; done；内核另有 python3 tam/tests/t_zhenghe.py、t_shaireg.py、t_zip_concurrency.py、t_coerce_setting.py、t_toolbox.py

免令牌模式（本机自用）

启动向导（start.bat / start.sh / python setup.py）会问一句：

? 启用访问令牌？（本机自用选 n）(Y/n)

• 选 n：写入 TAM_WEB_TOKEN= （空）+ TAM_NO_AUTH=1，浏览器打开 http://127.0.0.1:8848 直接可用，页面右上角令牌框留空。

• 选 y：没令牌就生成一个，已有则保持不变。

• 不想被问：python setup.py --no-token 或 python setup.py --token。

• 一键体检会识别 TAM_NO_AUTH=1，不再把空令牌当错误自动生成。

服务默认只监听 127.0.0.1，外部连不进来；一旦改成 0.0.0.0 或放到服务器，必须重新启用令牌。

布局编辑模式（仪表盘式网格）

右上角点【编辑布局】进入，再点【完成】退出。布局引擎是二维网格矩阵（坐标 x/y + 跨度 w/h），与 Grafana、react-grid-layout 同类机制。

说明：

• 控件粒度：每个统计数字、自动清设备提示条、账号列表、日志中文摘要、日志原始 JSON 各是独立控件。

• 响应式断点：宽屏 12 列 / 中屏 8 列 / 窄屏 4 列，三套布局分开保存，在手机上改动不会弄乱电脑上的布局。

• 手机触屏：长按约 0.2 秒才起拖，快滑仍然是页面滚动；拖到屏幕上下边缘会自动滚动。

• 性能：拖拽走 requestAnimationFrame + translate3d，实测单帧重算加渲染约 1.5ms。

• 布局存在浏览器 localStorage['tam.layout']（v3），换浏览器用导出/导入搬迁。

安全与合规

• 服务默认只监听 127.0.0.1；对外暴露必须加 HTTPS 反代与强令牌。

• data/ 目录含加密会话，勿进版本库；建议整盘或目录级加密。

• 主密钥丢失 = 所有会话不可恢复；请离线备份。

• 仅用于管理你自己拥有的账号。群发、批量拉人、自动化骚扰违反 Telegram 服务条款，可能导致账号被限制或永久封禁；本项目默认参数偏保守，请勿调高。

常见问题

tdata 导入报 BaseException: err

完整报错形如 opentele/utils.py, line 121, in __new__ / raise BaseException("err")， 前面还会打印一行 [__firstlineno__] ...。

原因：opentele 尚不支持 Python 3.13（上游 issue #133 / #145 至今未修）。 Python 3.13 给类新增了 __firstlineno__ / __static_attributes__，opentele 的 extend_class 校验不认，直接抛 BaseException（注意：它不是 Exception 子类， 常规 except 拦不住）。

最省事：python -m tam.cli doctor --fix，或在 Web 控制台点“一键体检”，会自动完成下面第 1 种修复。

手动方案二选一：

1. 打兼容补丁（快，可回滚）：

   python -m tam.cli fix-opentele          # 打补丁并验证导入
   python -m tam.cli fix-opentele --status # 只看状态
   python -m tam.cli fix-opentele --revert # 还原

   补丁只把那句断言性的 raise 改成放行，修改前会备份为 utils.py.tam-bak。 Web 控制台导入 tdata 时也会自动尝试这一步。

2. 改用 Python 3.12 重建虚拟环境（最稳妥）：

   rmdir /s /q .venv
   py -3.12 -m venv .venv
   .venv\Scripts\Activate.ps1
   pip install -r requirements.txt
   pip install -r requirements-optional.txt

导入报 {"detail":"unauthorized"} 或界面全是 401

Web 页面右上角的令牌要和 .env 里的 TAM_WEB_TOKEN 一致，输完按回车生效。

opentele 没装上

网页端 tdata 导入已改用内置解析器，不需要 opentele。 opentele 仅在机器人前端部分旧功能可能用到，是可选依赖：pip install -r requirements-optional.txt。 未安装不影响 Web 控制台与 CLI 的 tdata / session 导入。

已知限制

• 官方客户端同时登录上限为 3 个账号（Premium 4 个），本工具用独立 API 会话不受该限制，但每次新增授权都会出现在“已登录设备”里。

• 新号（尤其虚拟号）在冷却期内易触发 PeerFloodError，建议先养号：完善资料、正常收发、逐步提升活跃度。

• 同一 IP 下多账号高频活动会显著提高关联与封禁概率，建议一号一代理。

任务中心 / 线索库（v1.8）

把“对一批目标逐个执行”变成可观测、可停止的任务，完整链路是： 采集目标 → 建任务 → 富文本群发 → 逐目标看进度和失败原因。

最近发言人采集

• WebUI 「任务中心 → 采集发言人」，填群组与天数。

• 只取最近真实发过言的人，自动跳过机器人、已注销账号，减少对长期不活跃成员的无效触达。

• 结果自动入线索库，按 (来源, user_id) 去重，重复采集只更新活跃度。

• API：POST /api/tasks/collect

线索库

• 按来源统计人数与有用户名比例，支持一键导出 CSV（带 BOM，Excel 直接打开不乱码）。

• 可直接对某个来源“向它群发”，不用手工拷名单。

• 采集时勾选「同时存对话记录」后，Web 上每条线索 / 每个来源可点 「对话」 查看发言上下文。

• API：GET /api/leads、GET /api/leads/sources、GET /api/leads/messages、DELETE /api/leads

富文本群发

• 支持 {a|b} 变体（spintax）、{name} 个性化变量、HTML 富文本与可点击超链接、附件。

• 多账号轮询发送，带随机间隔；发送前可用 POST /api/message/preview 看展开样本与链接。

• API：POST /api/tasks/message

任务管理

• 进度条 + 成功/失败/已跳过统计，运行中每 3 秒自动刷新。

• “明细”看逐目标结果，失败原因自动归类（如 FloodWaitError 多少个）。

• “停止”为协商式：不再发新内容，剩余目标标为已跳过，已发出的不会撤回。

• API：GET /api/tasks、GET /api/tasks/{id}、POST /api/tasks/{id}/stop、DELETE /api/tasks/{id}、POST /api/tasks/cleanup

• Agent 工具：list_tasks、get_task、list_leads、lead_sources（只读）、stop_task（需 confirm）

常用环境变量（并发 / ZIP / 清设备）

写在 .env，也可在 Web 参数面板改完自动写回。启动时终端会打印当前 workers / 批量并发 / 清设备重试。

完整列表见 .env.example。

双部署 × 双前端（v1.9）

现在一个命令就能决定“装在哪”和“怎么用”：

python -m tam.cli run                      # 读 .env 里的 TAM_DEPLOY / TAM_FRONTEND
python -m tam.cli run --frontend both      # 临时覆盖：网页 + 机器人一起跑
python -m tam.cli run --deploy server --frontend bot
python -m tam.cli bot                      # 只跑机器人
python -m tam.cli serve                    # 只跑网页（老命令，没变）

两个开关

命令行参数 > 环境变量 > 默认值（local + web）。

两个前端分工不同，不是同一套东西换皮

• 网页控制台：管你自己托管在库里的号——登录、导入 tdata、养号、群发、线索库，以及接管满 24 小时自动清设备（带踢后校验与失败重试）。

• Telegram 机器人：管用户临时上传的号包——发个 ZIP 进去，处理完回传，不入库。

网页控制台（近期能力）

• AI 助手面板：右下角 / 顶栏唤出侧栏；OpenAI 兼容 API；权限预设（只读/安全/标准/完整）与逐项工具开关；账号范围限制；对话经服务端执行已授权工具。

• 导入进度：session / tdata / 字符串导入使用 NDJSON 流式进度，界面显示当前序号与结果。

• 二验：状态查询（含是否绑定辅助邮箱）、发起/取消官方 2FA 重置；支持单号与多选。

• 导出 tdata：真 Desktop 目录；缺 opentele 时可在界面一键安装。

• ZIP 工具：拆包、合并、注册时间、转 API、格式互转（session↔tdata）、Passkey 创建。

• 热重载：顶栏按钮真实重启后端进程（os.execv），不是刷新页面。

• 错误日志：服务端异常 / 5xx / 前端报错写入 SQLite + data/errors.log，可导出 JSON 上报。

TAM_FRONTEND=both 时网页与机器人共享配置与数据目录，但 Telegram 账号库仅网页/API 使用；机器人仍以临时号包为主。

机器人功能（菜单、命令两种用法都行）

筛活 /shaihuo、改 2FA /twofa、整合号包 /merge、双向测试 /bidir、隐私配置 /privacy、 格式互转 /convert、转 API /toapi、防找回 /norecover、筛 BAN /ban、筛料 /material、 清理账号 /clean、拆包 /unpack、销毁会话 /destroy、Passkey /passkey、注册时间 /regtime。 辅助：/start /help /status /id；管理员：/vip ID、/unvip ID、/gb（广播）。

故意没做的三项：踢设备、账号登录、在线取码——TAM 自己已经有更好的实现（带校验、带重试、 会话加密入库），机器人里的 /kick、/login 只负责把你引到那边，不重复造一份。

付费 / VIP

OKPAY_COST 留空就是不收费，任何人进来直接是 VIP（自用场景默认这样）。 填了 OKPAY_ID / OKPAY_TOKEN / OKPAY_COST 才会开付费门槛：下单后每 5 秒轮询，5 分钟不付自动关单， 付成自动升 VIP。管理员任何时候可以 /vip ID 手动开。

服务器部署提醒

--deploy server 会绑 0.0.0.0。请务必：别开 TAM_NO_AUTH=1、设好 TAM_WEB_TOKEN、 前面搭一层 HTTPS 反代、proxy.txt 配上代理池（否则所有号走服务器裸 IP，风控风险很高）。 启动时这几项没配好会直接在终端警告。

启动前体检（该提醒的都写在启动输出里）

python -m tam.cli run 会先把当前配置扫一遍，直接打在终端上，不用去翻文档：

----------------------------------------------------
  启动前体检（部署=server  前端=bot）
----------------------------------------------------
  ❌  机器人前端的依赖没装齐：python-telegram-bot[job-queue]、opentele
       → pip install -r requirements.txt
       → 只想用网页的话这些不用装，把 TAM_FRONTEND 改成 web 即可
  ❌  服务器模式未设 TAM_WEB_TOKEN，控制台会没有访问门槛。
       → python -m tam.cli init-key 生成一个填进 .env
  ⚠️  服务器模式会监听 0.0.0.0（全网可达），请在前面套一层 HTTPS 反代。
  ⚠️  没找到 proxy.txt，所有号会走服务器裸 IP，风控风险很高。
----------------------------------------------------

• ❌ 致命错误会直接阻断启动（缺依赖、缺 Token、服务器模式下 TAM_NO_AUTH=1 或没 TAM_WEB_TOKEN）， 真知道自己在干什么可以加 --force 继续。

• ⚠️ 警告只提醒不拦（没代理池、没管理员 ID、没配付费等于白嫖、密钥落盘……）。

• 依赖按前端分开查：只跑网页不会因为没装 python-telegram-bot 而报错，反之亦然。

• 缺 TAM_MASTER_KEY 这类问题也会输出一行人话提示，而不是抛一屏 traceback。