TgWitness / 文档

已测试的内容 →

参考 / 设置

Telegram · 账户与会话格式

支持通过手机、二维码或授权密钥登录,可导入 Telethon、Pyrogram 或 Telegram Desktop 的会话数据,并同时管理多个账户。

TgWitness / 文档 · 入门指南

入门指南

TgWitness 通过 MTProto 协议以 Telegram 用户账户(而非机器人)身份登录,使用 Telethon 实现。每个账户都位于独立的工作区中(在 API 和命令行工具中称为“工作区”),并拥有独立的会话、消息源、日志和签名密钥。

会话文件、会话字符串和认证密钥均属于账户授权凭证:任何 持有者均可代表该账户进行操作。这些凭证不包含消息历史记录。

[!警告] 请使用专用账户。Telegram 会限制并可能永久封禁其认为请求量过大的账户, 无论客户端或用途如何,且仅部分公开了 这些限制。请连接专门用于观察的账户,而非 个人账户或其他重要账户,并在专用 账户上创建 API ID / API 哈希。

一览#

您拥有 “添加账户”选项卡 您还需要
电话号码及其登录码的获取方式 电话 若已启用双因素认证(2FA),请输入密码
Telegram 在另一台设备上已打开 二维码 若已启用双因素认证(2FA),请输入密码
.session文件(Telethon 或 Pyrogram) 文件 可选的配套 JSON 文件,用于应用程序设置
.session + .json(同名) 文件(请同时选中) 通常没有其他内容
Telegram Desktop 中的 tdata 文件夹 文件(ZIP 压缩包) 若已设置,则为桌面端本地密码
Telethon StringSession(文本、.txt、.tgwitness-session) 文件 无需单独的 API 对
认证密钥和 DC 合并为一行,格式为 <512 hex>:<1–5> 文件(粘贴内容或文本文件) 无需单独的 API 对
包含会话或认证密钥的 .json 文件 无需单独的 API 对
一个授权密钥(512个十六进制字符)及其DC编号 认证密钥 可选用户 ID

TgWitness 根据文件内容而非文件名来识别文件。重命名文件 绝不会导致其被转换。

开始之前:API ID 和 API 哈希值#

您无需创建 Telegram API 应用程序即可登录。当未输入、 未导入或工作区中尚未保存任何密钥对时,TgWitness 会从其内置的 50 对公共 API 密钥对池中随机选取一对(tgwitness/api_pool.py),在首次登录时优先选用 Telegram Desktop 的密钥对, 并优先保留已保存的密钥对;其余候选密钥对将随机排序。若 Telegram 拒绝某组密钥对 (API_ID_INVALID, API_ID_PUBLISHED_FLOOD, UPDATE_APP_TO_LOGIN),则尝试下一组, 每次登录最多尝试八组;被拒绝的密钥对将被跳过,直至重启。用于登录的密钥对将 与该账户一同保存,并供该账户重复使用。

内置的配对是公开的:它们发布在 Telegram 客户端和库的开源代码中。API ID 和 API 哈希用于向 Telegram 标识应用程序, 但不会授予访问账户数据的权限。登录使用账户自身的授权方式:登录 码和双因素认证密码,或者该账户已授权的会话。每个 observation.started 记录中都会注明所使用的密钥对,因此内置密钥对在 法庭上的记录方式与您自己的密钥对相同。您也可以通过 my.telegram.org 输入您自己的密钥对。 根据本项目的经验,使用新的个人密钥对会导致大多数账户被注销,因此请仅在 案件需要您使用自己的应用程序时才使用:请使用专用账户创建该密钥对,并在 数据采集开始前输入(具体步骤如下)。

缺失的连接字段使用捆绑的 opentele2 2.0.0 目录中的确定性设备/操作系统组合: 桌面版 2040、Android 6、Android X 21724、iOS 10840、macOS 2834 以及 Web 2496。 Android 的源代码构建 ID 4 同样使用 Android 目录,该 ID 在 Telegram Android 的 BuildVars 中有明确标识。 Web 默认使用 A;若导入 K 应用版本后缀或 macos 语言包,则选择 K,而版本 0.7.0 则选择 Webogram。未知应用 ID 保持 Telethon 的主机 默认值。导入的字段始终优先,包括较旧的应用版本和空的 语言包。目录绝不会更改 API ID/哈希值。其版本快照会 经过明确审核,而非在登录时获取。保存的配置文件在更新后保持稳定。

account.getAuthorizations 报告 Telegram 保存的授权元数据;它 并非每次新调用 initConnection 的回显。请将其与实际发送的配置文件进行对比。 连接现有授权不会验证其对应的 API 哈希: initConnection 发送的是 API ID,而哈希则用于登录请求。

在新手机或二维码授权后,TgWitness会请求配置、最近的数据中心、 在线状态、语言(当语言包不为空时)、应用更新以及 服务条款更新,各请求间隔为0.3–1.5秒。 更新状态 会短暂地将账户标记为在线。该序列仅在登录完成时运行一次, 不会在数据导入、重新连接或重启时执行。授权信息会首先保存;若请求失败, 该序列将终止,既不重试也不丢弃登录信息。结果将 记录为account.initialized,其中包含错误名称而非响应正文。 Telegram自身的政策决定账户限制。

对于 tdesktop ,若未指定 tz_offset ,则使用服务器的本地 UTC 偏移量,并使用 opentele2 算法 将其四舍五入至 900 秒 (MIT 许可;许可协议详见 tgwitness/client_profiles.LICENSE )。该值在每次 连接时都会刷新,以反映夏令时变更。在所有平台上,导入的 tz_offset 均具有优先级,并将被精确保留,包括零值。其他 initConnection.params 条目将予以保留。 HTTP 登录表单接受文件导入返回的数值时区; 布尔值、分数以及超出支持范围的偏移量将被拒绝。

直接、SOCKS5 和 HTTP CONNECT 路由使用 Telethon 的 ConnectionTcpObfuscated (经过混淆的简化版 MTProto)。HTTPS CONNECT 保持与代理之间的 TLS 连接,并在隧道内部使用 相同的混淆传输协议。MTProxy 保留其必需的 随机化中间传输和密钥处理机制。路由切换采用 相同的选择。 混淆处理会改变数据包的帧结构;它不会向 Telegram 隐藏账户 或其客户端元数据,也不意味着能够规避相关限制。

在连接授权客户端后,TgWitness 会检查配置、最近的数据中心、 当前授权状态、已审核的层级基线、语言、应用更新 以及服务条款更新。 这些诊断操作针对每个客户端实例仅执行一次, 且在数据收集之前进行,结果将连同执行时间一并显示在连接详情中。 account.connection_checked 会记录结果,但不包含会话哈希、IP 地址、 令牌或 API 哈希。这些操作绝不会接受条款或安装更新。若请求 失败或触发 FloodWait,后续请求将停止;若缺少结果,则该结果将保持未知状态。 本地检查仍可报告结果,而网络检查则会被跳过。 当启用严格选择聊天功能时,系统不会请求当前 授权信息,该检查将显示为已跳过。

登录后以及每次建立新连接时,TgWitness 会读取该账户的敏感 内容设置。 当该设置处于关闭状态且 Telegram 允许更改时,TgWitness 会将其开启, 以便保存 Telegram 标记为敏感(18+)的内容,并记录 account.content_settings。该设置属于该账户,并在所有 Telegram 应用中生效。若启用了“严格选择聊天”功能,则该设置保持不变;请在登录前开启该功能。

对同一工作区连接的并行恢复请求将共享其客户端,并 等待该连接的建立完成。如果某次尝试失败或被取消,系统将释放 该资源,以便下一个请求重试。如果在连接建立过程中,已保存的凭据、客户端或授权状态 发生变化,则较早的尝试将停止,而非报告连接已就绪。

FloodWait 诊断信息会保留失败的 TL 方法、任何 Takeout/range 包装器、 服务器请求的等待时间以及 telegram.backoff 中的有效截止时间。 在请求暂停期间,连接详细信息会显示方法和截止时间。 该诊断信息包含自该客户端创建以来 按方法统计的客户端调用计数器;这些计数器会单独统计嵌套的对等方解析,但不计入数据包 或 Telethon 的内部重试尝试。当前计数器也可通过状态 API 中的 collector.rpc_activity 获取。 不包含任何请求参数、用户名、访问 哈希值或异常文本。最后一条诊断信息和完整的截止时间 在重启后仍会保留。早期没有方法记录的等待无法 追溯归因。请参阅源代码审查的导出限制以及 发现与历史数据获取之间的区别。

official_app=True或False是 Telegram 的当前授权标志。这两个 值均无法确定该账户是受限、受信任还是处于观察状态。 现有的证据模式 account.devices 快照仍保留所有 已登录设备的历史记录;连接诊断仅保留当前设备的描述。

连接前,建议性检查会将 API 平台、语言包、 设备/操作系统和应用版本格式、移动系统区域设置,以及 Telethon 的实际 模式层与已审核的目录基线进行比对。警告会显示在服务器 日志和账户状态元数据中;它们绝不会替换导入的值或更改 模式层。模式层不一致是需要审查兼容性的信号;账户的 自身连接状态会显示是否正常工作。 无论使用何种客户端配置文件,Telegram 都会在其 端决定限制条件。断开连接的账户状态 将使用已保存的配置文件,而非生成另一份设备描述。

若要改用您自己的应用程序:

  1. 打开 my.telegram.org,并使用您拥有的任意手机号码 登录。验证码将发送到 Telegram 应用中,而非通过短信。
  2. 选择 API 开发工具。
  3. 创建应用程序:任意标题和简称(5–32 个字母),平台为桌面版。 URL 和描述可留空。
  4. 复制 App api_id(一个数字)和 App api_hash(32 个十六进制字符)。

在登录表单下方的面板中,有“API ID + 哈希”字段。您可以在 API ID 字段中粘贴一组 api_id:api_hash,两个字段将自动填充。一组 即可用于您所有的账户。成功登录后,该信息将以加密形式保存在 该工作区中,且绝不会发回浏览器。

涉及三种不同的凭证:

秘密 打开 托管位置
面板令牌 TgWitness 网页控制面板 数据目录中的 panel-token.txt,或 TGWITNESS_TOKEN
API ID + 哈希值 本身不包含任何内容;仅用于标识该应用程序 可通过 my.telegram.org 进行内置配对、导入设置或使用您自己的应用程序
账户授权 Telegram 账号 可通过手机/二维码登录创建,或作为会话导入

如果必须通过代理访问 Telegram,请先在 更多工具→账户→设置→连接设置→更改连接路径中进行设置。

电话号码#

  1. 打开更多工具→账户,切换至电话选项卡,并以国际格式输入号码, 例如+44 7700 900123。空格和连字符将自动去除。
  2. 点击“继续”。API ID 和哈希值可留空。
  3. 输入 Telegram 发送的代码,通常发送至 Telegram 应用;由 Telegram 决定是否发送短信。
  4. 如果该账户启用了双重验证,请输入该密码。这并非控制面板 令牌,也不是设备密码。
  5. 登录后查看显示的账户 ID,然后选择消息来源。

登录凭据和双因素认证(2FA)密码绝不会写入磁盘。

二维码#

当该账户已在手机或另一台计算机上登录时,请使用此功能。

  1. 点击“QR 码”→ 显示 QR 码。API ID 和哈希值可留空。
  2. 在已登录的设备上:设置 → 设备 → 关联桌面设备,扫描二维码 并确认。
  3. 若 Telegram 要求输入双因素认证(2FA)密码,请在 TgWitness 中输入该密码。

该二维码是在本地生成的。二维码会过期;请点击“生成另一个二维码 ”重新尝试。锁定面板、切换工作区或开始另一轮登录操作将取消 待处理的二维码。

认证密钥 + DC ID#

授权密钥(Auth Key)是每个 Telegram 会话背后的 256 字节原始授权数据,以 512 个十六进制字符的形式表示,并附带数据中心编号 DC 1–5。

  1. “Auth key”选项卡。请粘贴完整的密钥;包含“…”的缩短版密钥无法使用。
  2. 请选择随密钥提供的 DC ID。
  3. 可选输入用户 ID。若 Telegram 报告的 账户信息不一致,TgWitness 将拒绝连接。
  4. Press Connect 账号。

授权密钥(512 个字符)并非 API 哈希(32 个字符)。同一密钥也可 以 JSON 格式导入,详见“账户 JSON”。

账户文件#

打开添加账户→文件,选择最多四个属于同一账户的文件(总计 8 MiB),点击检查文件,然后点击连接账户。选择文件或 粘贴会话文本不会发送任何内容;点击检查文件会将文件发送至您的TgWitness服务器, 该服务器无需登录即可读取这些文件,并显示其找到的会话。

文件、授权密钥和批量导入表单会在连接前显示并行会话警告。 默认情况下,导入的授权将被重复使用。当其密钥在此处使用时,请保持原始 客户端处于关闭状态。文件和授权密钥还提供 创建独立授权选项,具体说明见下文。批量导入仍使用 直接模式。手机和交互式二维码登录会创建独立的授权。 导入表单中会持续显示该警告标题;当提供文件或密钥/会话字符串时,其完整说明会 自动展开。阅读后可将其折叠, 以便在手机上继续使用文件选择器和连接控件。

已验证的部署(Phala Cloud、Intel TDX)不会对 导入的密钥进行收集。在此情况下,文件和认证密钥仅在选中创建独立 授权时才能连接;批量导入将被拒绝。手机和二维码登录照常工作。

  • 文件在您的 TgWitness 服务器内存中进行转换。上传内容不会被存储, ZIP 文件不会解压到磁盘,也不会连接任何外部服务。
  • 生成的会话记录随后将与 Telegram 进行核对。如果文件中包含用户 ID, 则该 ID 必须与 Telegram 报告的账户信息一致。
  • 描述不同账户或不同 API 凭据的文件将被拒绝 而非仅选择其中一个。
  • 密码或会话文本字段用于存储 TData 本地密码字段,该框用于粘贴 StringSession 以及无需登录即可读取文件(在无需 联系 Telegram 的情况下填写表单)。 粘贴 StringSession 会清空已选文件,而选择 文件会清空已粘贴的文本,因此验证和连接操作均采用最新选择。 更改密码后,请再次点击检查文件。

创建独立授权#

请选择“在连接前创建独立授权”并导入文件,或 选择授权密钥。TgWitness会短暂连接导入的捐赠者设备,利用其批准 新客户端的二维码登录令牌,并在批准后立即断开与捐赠者的连接。 新客户端拥有独立的授权密钥和单独选择的桌面 配置文件。由捐赠者提供的 API 凭据和设备配置文件仅用于 与捐赠者的连接。现有授权不会被注销或撤销。

在此步骤中,请保持捐赠者的原始客户端完全关闭。初始 连接仍使用其复制的密钥,因此此模式无法消除该初始 并行使用风险。一旦建立新的授权连接,所有者即可重新打开 原始客户端,并同时使用这两个客户端。 交互式二维码登录允许 原始客户端在此处无需复制或连接其密钥即可批准登录。

请勿注销或结束捐赠者的会话。当批准 QR 登录的会话结束时,Telegram 也会终止其所批准的会话;在实际测试中,新 授权会在捐赠者注销后一秒内停止。导入操作会记录 捐赠者的会话信息(session_origin.approved_by:设备、API ID 和创建时间)。 会话列表会将其标记为已结束,结束会话会拒绝该会话,而结束所有其他会话 和将此设为唯一会话则会让捐赠者保持登录状态。

如果 Telegram 要求进行双因素认证,此模式会 twoFA 选定 JSON 文件中的内容(若存在), 否则将要求输入密码。若导入的密码被拒绝,系统将返回密码输入表单。 密码不会被保存。候选密钥将以加密形式保存在 independent_login.enc,包括数据中心迁移期间的变更。发生 中断后,请选择相同的捐赠者并选中此选项以恢复已保存的候选密钥。 在批准前会通过 help.getAppConfig 进行验证;若源账户处于冻结状态, 则在此处终止。若 Telegram 在批准登录前拒绝了源账户,未获批准的 候选密钥将被丢弃,并可重新开始导入。只有当 Telegram 报告该候选账户未登录时, 另一个源账户才会替换已保存的候选账户;已登录或正在等待双因素认证密码的 候选账户将予以保留。 该工作区仍为该账户保留;导入失败不会删除 新工作区。请保留其数据目录和保险库密钥。最终的凭据和 account.authorized 日志记录中包含导入方法、输入格式和 捐赠者 API ID,但不包含捐赠者密钥或密码。

2026年11月5日,一个专用账户通过了Telethon、Pyrogram 和TData捐赠者的实时验证:2FA验证完成、生成独特的新授权密钥、捐赠者与新客户端的并发访问 ,以及公共频道的阅读操作。 在 Telethon 案例中, 系统还在密码输入步骤中断后恢复了已保存的候选会话。每次新的 授权都完成了登录后的六个初始化请求,且其签名的 日志已通过验证。原始会话在提供的四种格式中均保持可用。

Telegram 的 RPC 错误数据库将 FRESH_CHANGE_ADMINS_FORBIDDEN 与更改管理员相关联,FRESH_CHANGE_PHONE_FORBIDDEN 与更改电话号码相关联,而 FRESH_RESET_AUTHORISATION_FORBIDDEN 则与 撤销其他会话、更改其有效期或注册通行密钥相关联。 SESSION_TOO_FRESH_*和PASSWORD_TOO_FRESH_*涉及所有权转移以及 收入或礼品的提取。这些并非数据收集操作;新登录并不 意味着全面禁止在24小时内读取数据。导出操作可能会单独返回 TAKEOUT_INIT_DELAY_*。TgWitness会保留服务器请求的暂停状态,且不会自动重试 令牌接受或撤销会话以规避限制。

更多工具 → 账户 → 账户安全 → 该账户的会话 → 结束所有其他会话:应 操作员请求调用 auth.resetAuthorizations,并将会话 数量(结束前和结束后的)记录到 account.all_other_sessions_terminated 中。Telegram 仅接受来自已登录满 24 小时的会话发出的此请求。 当此工作区通过导入的会话使用二维码登录时,批准该登录的会话 将保持登录状态:TgWitness 使用 account.resetAuthorization 逐一终止其他会话,并 记录 kept_approving_session。将该会话设为唯一会话后,系统将以此为由停止操作 且不更改密码。

将此设为唯一会话:对于通过此工作区登录生成的密钥,执行相同操作,若账户未启用两步验证,则为其启用。面板会显示该密码一次;TgWitness 仅在显示前将其保存在工作区保险库中。日志记录 session.exclusive_from。如果 Telegram 随后列出另一个会话,日志将记录 session.exclusive_ended ,面板将触发警报。验证器会打印这两项信息。

当 Telegram 允许将此设为唯一会话时,这相当于定时执行同一操作。该 选项会出现在此工作区中创建的密钥的该账户的会话下,并被 记录为 session.exclusive_automatic。在观察期间,收集器每五 分钟检查一次,自该密钥的 account.authorized 记录以来是否已过去 24 小时—— 在此之前,Telegram 会返回 FRESH_RESET_AUTHORISATION_FORBIDDEN 响应——然后执行同一 操作一次。成功执行将记录为 session.exclusive_from,与手动按钮的效果相同。 若操作被拒绝,则会以session.exclusive_postponed的形式记录一次(附带Telegram给出的原因), 收集器将以递增的延迟(最长可达六小时)进行重试。此处只读模式无效: 结束会话属于账户安全操作,而非聊天操作。

自动运行生成的两步验证密码会在 Telegram 设置该密码之前,使用工作区密钥加密并保存到工作区保险库中。控制面板会从 POST /api/account/sessions/only/password,该操作会将其删除,并在您打开该账户的“会话”时,将其显示在与手动流程相同的对话框中。连接页面会提示有密码待取。该密码绝不会进入日志,且在显示之前即使重启也能保留。

在观察过程中,新会话也会被报告:当 Telegram 的会话列表新增一条记录时, account.sessions记录会在added下为其命名,控制面板会触发警报,并显示 该快照中的设备、应用程序和国家/地区信息。

见证探针#

更多工具 → 账户 → 账户安全 → 见证人探针用于检查其他客户端是否接收该账户的 更新。添加一个使用不同 Telegram 账户登录且拥有独立 会话密钥的第二个工作区,创建一个包含这两个账户的私人群组,然后将该群组设为探针 聊天,将第二个工作区设为见证人工作区,并开启探针功能。两个账户 均需关闭只读模式,且见证人工作区必须处于观察状态。

在观察过程中,该工作区每60–120秒向群组发送一次probe:<n>:<token> 并记录probe.sent。见证者响应ack:<n>:<token>并记录probe.seen和 probe.ack_sent。若确认应答在20秒内作为实时更新到达该会话,则 记录为probe.acked。否则,工作区将读取群组的近期历史记录。 若在历史记录中 发现某条确认但未以实时更新形式送达,则将其记录为 coverage.gap,原因 为 probe_ack_missed_live:控制面板将触发警报,并标记事件接收为失败,直至 后续确认以实时更新形式送达(connection.restored,原因 probe_ack_live)。未记录任何确认为 probe.unanswered;等待期间的连接中断或无法读取的历史记录则记录为 probe.inconclusive。只读状态、Telegram 限制及 FloodWait 暂停均仅记录一次 ,标记为 probe.skipped。

Telethon .session#

产品简介 基于 Telethon 的工具生成的 SQLite 数据库,例如 my_account.session
获得以下机构认可: 表格 sessions(连同 dc_id、server_address、port、auth_key)和 version = 7 或 8
要求 仅有一行授权会话记录;一个封闭且完整的数据库

请先关闭创建该文件的程序。如果其旁边存在 my_account.session-journal 或 my_account.session-wal,则表示数据库尚未最终确定:请正常打开并 关闭原始客户端。删除这些辅助文件可能会导致副本损坏。

Pyrogram .session#

产品简介 基于 Pyrogram 的工具生成的 SQLite 数据库
获得以下机构认可: 表 sessions 包含 dc_id、auth_key、test_mode、user_id、is_bot;version = 2 或 3
要求 生产网络上仅允许一个授权用户会话。机器人和测试数据中心(test-DC)会话将被拒绝

登录时,系统会将存储的用户 ID 与 Telegram 进行比对。

会话 + JSON 对#

账户通常以两个同名文件的形式分发,例如 447700900123.session 和 447700900123.json。请同时选中这两个文件。

  • 根据 JSON 信息,TgWitness 使用 app_id/api_id 和 app_hash/api_hash,因此您 通常无需手动输入 API 凭据。
  • 连接配置文件使用 device_model(别名 device)、system_version (别名 sdk)、app_version、lang_code、system_lang_code(别名 system_lang_pack)、 lang_pack 以及可选的 tz_offset(以秒为单位,相对于 UTC 的偏移量,范围为 -43200 至 50400)。 用户提供的字段优先于生成的默认值和面板/浏览器的 语言设置。冲突的别名将被拒绝。解析后的配置文件将保存在 加密的工作区凭据中,并在重启后被重复使用,其中包括其应用版本。
  • phone、代理设置和设备令牌将被忽略。twoFA仅在 选择创建独立授权时为只读;直接导入时将忽略该字段。
  • 不包含受支持授权字段的 JSON 仅为元数据。请添加其会话 文件,或继续使用手机或二维码登录。包含受支持会话或 授权密钥的 JSON 可独立完成授权;详见账户 JSON。

Telegram 桌面版 (TData)#

TData 是 Telegram Desktop 应用程序(来自 desktop.telegram.org 的跨平台 应用程序)中的 tdata 文件夹。

系统 默认位置:tdata
Windows %APPDATA%\Telegram Desktop\tdata(便携版 Telegram:位于 Telegram.exe 旁边)
Linux ~/.local/share/TelegramDesktop/tdata
macOS ~/Library/Application Support/Telegram Desktop/tdata

导入方法:

并行会话警告。直接导入 TData 会复用 Telegram Desktop 的授权 密钥。请勿在 Desktop 和 TgWitness 中同时使用该密钥。Telegram 可能会通过 AUTH_KEY_DUPLICATED 使授权失效,导致两个实例均无法使用,直至重新登录。

请完全退出 Desktop(包括其系统托盘进程),并在 TgWitness 使用导入的会话期间保持该副本关闭。请退出程序,切勿注销或撤销会话: 撤销操作也会使导入的副本失效。如果您需要同时运行两个客户端, 请选择创建独立授权,并在 新登录成功之前保持 Desktop 关闭,或者通过手机或二维码登录 TgWitness。建议使用 专用账户,但这并不能确保克隆密钥在并行使用时是安全的。

这同样适用于导入的 .session 文件、StringSession文本及认证密钥十六进制值。 其他拥有独立创建的授权的客户端可以保持登录状态。 请参阅Telegram的AUTH_KEY_DUPLICATED文档。

  1. 完全退出 Telegram Desktop。
  2. 从 tdata 中提取仅包含以下两项内容的 ZIP 压缩包:

    • key_datas
    • 其旁以 s 结尾的 16 个字符的文件,通常为 D877F783D5D3EF8Cs

    将整个文件夹及其媒体缓存打包为 ZIP 文件通常会超出限制 (512 条记录,解压后 32 MiB)。 3. 在“文件”中选择该 ZIP 文件。如果 Telegram Desktop 设置了本地密码,请先在 “密码”或“会话文本”栏中输入该密码。这并非双因素认证(2FA)密码。

支持功能:每个存档仅限一个账户,采用现代key_datas/key_data0/key_data1存储技术, 本地密码保护。不支持功能:包含多个已登录账户的文件夹、旧版桌面 布局、受密码保护的ZIP文件,以及独立的原生macOS应用“Telegram for macOS”。

Telethon StringSession#

一行文本,通常以 1 开头,长度约为 350 个字符。请将其 作为 .txt 或 .tgwitness-session 文件(最大 4 KiB)加载,或将其粘贴到 “通行码”或“会话文本”下方。仅接受 Telethon 字符串;Pyrogram 和 TDLib 字符串采用不同的格式。

授权密钥和 DC 合为一行#

账户列表通常以 <512 hexadecimal characters>:<DC id> 的形式携带原始授权信息, 例如 a1b2…ef:5。请将该行粘贴在通行码或会话文本下方,将其作为 文本文件加载,或将其放入账户 JSON 的 session 字段中。TgWitness 将 DC 1–5 映射到与 auth_key + dc_id JSON 导入相同的正式地址,并 以授权密钥 HEX 和 DC的格式进行报告。任何其他 DC 编号或密钥长度均会被拒绝。

账户 JSON#

一个 JSON 对象,大小不超过 64 KiB,存储在以 .json 结尾的文件中。

字段(别名) 含义
api_id (app_id) 应用程序 ID,一个正数
api_hash (app_hash) 应用程序哈希值,32个十六进制字符
string_session(session_string、session_str;旧版 session) Telethon StringSession 文本,或 <512 hexadecimal characters>:<DC id>,而非文件名
auth_key (auth_key_hex) + dc_id 完整的 512 个字符的认证密钥和 DC 1–5
user_id (id) 可选;在保存授权之前,需与 Telegram 进行比对验证
device_model (device) 连接设备说明
system_version (sdk) 连接操作系统版本
app_version 发送至 Telegram 的应用程序版本
lang_code, system_lang_code (system_lang_pack), lang_pack 客户端语言、系统语言和客户端语言包;允许使用空的lang_pack
tz_offset 可选的 UTC 偏移量(以秒为单位),通过 initConnection.params 发送;整数或十进制整数字符串

如果别名和主名称同时存在,它们必须一致。显式的 Telethon 会话字段优先于其他格式的通用 session 数据块。如果 两者都包含可识别的 Telethon 会话,则它们必须描述相同的授权。 如果没有显式字段,session 必须是有效的 Telethon StringSession,或者是以 <512 hexadecimal characters>:<DC id> 形式表示的授权密钥 和 DC。示例:

{ "app_id": 1234567, "app_hash": "0123456789abcdef0123456789abcdef" }
{
  "api_id": 1234567,
  "api_hash": "0123456789abcdef0123456789abcdef",
  "auth_key": "REPLACE_WITH_ALL_512_HEXADECIMAL_CHARACTERS",
  "dc_id": 2,
  "user_id": 123456789
}

第一个示例仅需填写 API 凭据;您可通过手机或二维码登录,或添加会话 文件。不支持批量列表(即账户的 JSON 数组)。

识别您拥有的内容#

您会看到 它是一个 用法
*.session;在文本编辑器中打开后,顶部显示为 SQLite format 3 Telethon 或 Pyrogram SQLite 文件(自动检测)
一个名为 tdata 的文件夹,其中包含 key_datas Telegram 桌面版 TData 将两个文件打包为 ZIP 文件,然后进入“文件”
以 1 开头的一行文本,约 350 个字符 Telethon StringSession 文件
一行文本 512 characters 0-9a-f,随后是 : 和一个数字 1–5 授权密钥和 DC 文件、箱密码或会话文本
*.json 搭配 app_id/app_hash 配套元数据 文件及其会话
*.json 搭配 auth_key 或 string_session 账户 JSON 文件
512 个字符 0-9a-f 授权密钥 认证密钥
32 个字符 0-9a-f API 哈希值 API ID + 哈希值
来自 TDLib 应用的 td.binlog 或 db.sqlite TDLib 存储 不支持
123456789:AA… 机器人令牌 不支持

不受支持的格式#

格式 备选方案
TDLib 存储(td.binlog)和 TDLib 导出功能 通过手机或二维码登录
Pyrogram 会话字符串 请使用 Pyrogram .session 文件,或通过手机/二维码扫描
TData 包含多个已登录账户 请在 Telegram Desktop 中注销其他账户,或使用各账户各自的会话文件
机器人令牌 不支持:TgWitness 以用户账户身份进行监控
包含大量账户的 CSV/JSON 列表 通过账户 → 导入账户导入受支持的会话文件,或在独立的工作区中通过手机号/二维码登录
测试数据中心(Test-DC)或机器人会话 请使用正式版用户账户

多个账户#

点击账户选择器旁边的+号,或打开 更多工具 → 账户 → 设置 → 连接设置 → 工作区,输入标签并 登录。

  • 支持任意数量的工作区,包括主工作区。每个工作区都有独立的会话、代理 路由、消息源、捕获策略、日志、签名密钥、检查点和导出功能。
  • 切换显示的工作区不会暂停其他工作区。
  • 日志始终与创建它的账户绑定。使用其他 账户登录需要另一个工作区,且一个账户不能分配给两个 工作区。
  • 主面板令牌可控制所有工作区。授予的访问权限可将其他用户的访问范围限制在选定的账户和聊天群组内,并可设置独立的权限和会话限制。
  • 账户会重命名一个工作区,并删除一个已添加的工作区,连同其会话、日志、 来源和签名密钥一并删除。主工作区无法从面板中删除。

批量导入和账户分组#

使用“账户”→“导入账户”可添加多个账户,按文件基名配对文件 并查看每个登录结果。每个账户都有独立的工作区。

“组”可将相关账户集中管理,同时不会合并其会话、密钥或 证据。在“账户”页面中点击“开放组”可跳转至其页面: /groups/<id>:

  • 账户:每位成员的连接路径、观察记录和最后一条消息,并提供 “全部启动”和“全部暂停”功能。
  • 需要关注:已注销、不可用或存在 连接、接收、来源或媒体问题的账户;每个名称均链接至其卡片。
  • 多个账户可见的聊天记录包括: 共享来源、正在查看这些记录的账户以及 可用工作区观察期间(最长七天)内的中断情况。使用 N 个账户进行导出时, 会将频道或超级群组的导出内容分配给这些账户,并为一个存档文件签名。
  • 导出组:包含一个 ZIP,其中包含每个账户的已签名导出文件,位于 accounts/ ,并 manifest.json 列出其SHA-256和密钥指纹,由主 工作区在 manifest.signature.json。请使用 python -m tgwitness.verify 并使用该账户的可信指纹进行验证。

成员共享群组的设置;单个账户可保留其自身的设置值。 请参阅共享设置、 导入与群组指南 以及 MTProxy 数据池仪表盘。

退出登录#

更多工具 → 账户 → 退出 Telegram(暂停观察)会要求 Telegram 终止该 会话,因此该会话也会从账户的设置 → 设备中消失,并从 工作区保险库中移除该会话。日志、数据源、设置和签名密钥将保留,且 日志会记录此次退出操作。 该工作区仍归属于其账户:只有该 账户才能再次连接到它。如果 Telegram 没有响应,该会话仍会在此处被移除 ,且面板会显示相应提示;请在 Telegram 的设置→设备中结束该会话。

当 Telegram 结束会话时#

如果 Telegram 禁用、冻结或注销该账户,或者从另一台设备终止会话, 日志会记录原因、Telegram 错误、路由和数据中心。该账户的 健康状况显示下载账户丢失报告:这是一个经过签名的 JSON 文件,其中包含丢失前 24 小时的日志记录,即连接、路由、会话、账户通知和覆盖 缺口,每项都带有相应的日志哈希值和签名。请使用 python verify.py tgwitness-account-loss.json --fingerprint COLLECTOR_FP;证据导出 中包含完整的哈希链。当被冻结的账户尝试连接时,系统会在监控期间检测到该情况,并 禁用其发送和加入操作。

确保账户文件的安全#

  • 请将每个 .session、TData ZIP、StringSession、Auth Key 和账户 JSON 视为 密码。TgWitness 会将导入的授权信息保存在其加密保险库中;您可以在 之后删除原始文件。
  • 请勿在两个程序中同时运行同一授权。Telegram 可能会撤销该授权 (AUTH_KEY_DUPLICATED),导致两个程序均无法运行。
  • 已过期或被撤销的会话无法通过转换恢复。请重新登录。

故障排除#

消息或症状 操作指南
无法读取此会话。请关闭其原始客户端…… SQLite 文件处于打开状态或未完成状态(-journal/-wal 旁路文件)。请正确关闭原始程序,然后重新复制该文件。
支持的 Telethon SQLite 模式:7 和 8 / Pyrogram … 2 和 3 该文件由一个非常旧或未知版本的库生成。请改用手机/二维码登录。
仅支持授权的生产环境用户会话 该 Pyrogram 文件属于某个机器人或测试网络。
TData 存档已超过 512 条记录或 32 MiB 仅包含 ZIP 文件 key_datas 和 D877F783D5D3EF8Cs,不包含整个文件夹。
无法解密 TData。请检查桌面本地密码 在“密码”或“会话文本”栏中输入 Telegram 桌面版的本地密码。
每次仅导入一个 TData 账户 Telegram Desktop 包含多个账户;请参阅“不受支持的格式”。
选定的文件描述了不同的账户或 API 凭据 仅选择一个账户的文件。
JSON 中未包含任何受支持的 API 凭据或授权信息 请检查 Account JSON 中的字段名称。
仅限 API 元数据 该 JSON 文件中未包含会话信息。请添加 .session 文件,或使用手机/二维码。
Auth Key HEX 必须包含全部 512 个十六进制字符 密钥被截断或包含…。
账户 ID 与导入的账户不匹配 该文件的用户 ID 与 Telegram 报告的不一致;该文件属于另一个账户。
该账户已属于另一个工作区 请打开该工作区,而非重复添加该账户。
已连接,但在更多工具→来源的聊天列表中缺少一个私人群组 检查成员资格。选择器会检查前1,000个对话;可在更多工具→参数中提高该限制。
代理连接失败 检查路由和 IP 模式。自动模式MTProxy会尝试其他可用的入口。隐藏地址模式会等待;直接模式作为最后手段,可在配置的延迟后直接连接。参见路由模式。

另请参阅:代理和加密的连接与安全设置, 以及登录后数据采集的具体工作原理。