TgWitness / 文件說明

已測試的內容 →

參考資料 / 設定

Telegram · 帳戶與會話格式

可透過手機、QR 碼或授權金鑰登入,匯入 Telethon、Pyrogram 或 Telegram Desktop 的會話紀錄,並同時管理多個帳戶。

TgWitness / 文件說明 · 開始使用

開始使用

TgWitness 透過 MTProto 協議,使用 Telethon 以 Telegram 用戶帳戶(而非機器人)身分登入。每個帳戶皆位於獨立的工作區中(在 API 和命令列工具中稱為「工作區」),並擁有專屬的會話、來源、日誌及簽名金鑰。

會話檔案、會話字串及認證金鑰均屬帳戶授權憑證:凡 持有其中任何一項者,皆可代表該帳戶進行操作。這些資料不包含訊息歷史紀錄。

[!警告] 請使用專用帳戶。Telegram 會針對其認為過量的請求量進行限制,甚至可能永久封禁帳戶, 無論客戶端或用途為何,且僅部分公開相關限制規範。 請連接專為觀察準備的帳戶,而非 個人或其他有價值的帳戶,並在專用 帳戶上建立 API ID / API 雜湊值。

一覽#

您現有的內容 「新增帳戶」分頁 您還需要
電話號碼及其登入代碼的存取權限 電話 若已啟用,則為雙因素驗證 (2FA) 密碼
Telegram 已在另一台裝置上開啟 QR 碼 若已啟用,則為雙因素驗證 (2FA) 密碼
.session 檔案(Telethon 或 Pyrogram) 檔案 可選的 JSON 檔案,用於應用程式設定
.session + .json(名稱相同) 檔案(請選取兩者) 通常沒有其他內容
Telegram 桌面版中的「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 識別該應用程式,但不會授予存取帳戶資料的權限。登入過程使用帳戶自身的授權機制:登入 碼和雙因素驗證 (2FA) 密碼,或是該帳戶已授權的會話。每 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 目錄,此資訊可於 Telegram Android 的 BuildVars 中查證。 Web 預設為 A;若導入 K 應用程式版本後綴或 macos 語言套件,則選取 K;版本 0.7.0 則選取 Webogram。未知應用程式 ID 將維持 Telethon 的主機 預設值。導入的欄位始終具有優先權,包括較舊的應用程式版本及空的 語言套件。目錄絕不會變更 API ID/雜湊值。其版本快照會 經過明確審查,而非於登入時自動擷取。儲存的設定檔在更新後仍保持穩定。

account.getAuthorizations 會回報 Telegram 儲存的授權元資料;這 並非每次執行 initConnection 時的即時回響。請將其與實際傳送的設定檔進行比對。 連接現有授權並不會驗證其對應的 API 雜湊值: initConnection 會傳送 API ID,而雜湊值則用於登入請求。

在進行新的手機或 QR 碼授權後,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 個字母),平台選「桌面版」。 網址與描述欄位可留空。
  4. 請複製 App api_id(一個數字)和 App api_hash(32 個十六進位字元)。

在登入表單下方的面板中,會顯示「API ID + Hash」。您可將一組 api_id:api_hash 組合貼上至 API ID 欄位,系統便會自動填入兩個欄位。同一組組合可 適用於您所有的帳戶。成功登入後,該組合將以加密形式儲存於 該工作區內,且絕不會傳回瀏覽器。

涉及三種不同的憑證:

機密 開啟 存放位置
面板代幣 TgWitness 網頁控制面板 資料目錄中的 panel-token.txt,或 TGWITNESS_TOKEN
API ID + 雜湊值 本身並無特殊含義;僅用於識別該應用程式 可透過內建配對、匯入設定,或於 my.telegram.org 建立您專屬的應用程式
帳戶授權 Telegram 帳號 可透過手機/QR 碼登入建立,或作為會話匯入

若必須透過代理伺服器連線至 Telegram,請先前往「 更多工具」→「帳戶」→「設定」→「連線設定」→「變更連線路徑」進行設定。

電話號碼#

  1. 開啟「更多工具」→「帳戶」,切換至「電話」分頁,並以國際格式輸入號碼, 例如 +44 7700 900123。空格和連字號會自動移除。
  2. 按下「繼續」。API ID + Hash 欄位可留空。
  3. 請輸入 Telegram 傳送的代碼,通常會傳送至 Telegram 應用程式;是否發送 SMS 由 Telegram 決定。
  4. 若該帳號啟用了兩步驟驗證,請輸入該密碼。此密碼並非控制面板 代幣,亦非裝置通行碼。
  5. 登入後請確認顯示的帳號 ID,然後選擇資料來源。

登入代碼與雙因素驗證 (2FA) 密碼絕不會寫入磁碟。

QR 碼#

當該帳號已在手機或另一台電腦上登入時,請使用此功能。

  1. 點擊「QR 碼」→ 顯示 QR 碼。API ID + Hash 欄位可留空。
  2. 在已登入的裝置上:設定 → 裝置 → 連結桌面裝置,掃描條碼 並確認。
  3. 若 Telegram 要求,請在 TgWitness 中輸入雙因素驗證 (2FA) 密碼。

此 QR 碼圖像係於本地端產生。QR 碼會過期;請按「產生另一個 QR 碼」 以重新嘗試。若鎖定面板、切換工作區或啟動另一組登入程序,將取消 待處理的 QR 碼。

授權金鑰 + DC 識別碼#

授權金鑰(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 伺服器, 該伺服器會在未登入的情況下讀取這些檔案,並顯示其找到的對話紀錄。

「檔案」、「授權金鑰」及「批量匯入」表單會在連線前顯示 「並行會話」警告。預設情況下,匯入的授權將被重複使用。當其金鑰 在此處使用時,請保持原始 客戶端關閉。檔案與授權金鑰亦提供 「建立獨立授權」功能,詳見下文說明。批量匯入仍使用 直接模式。手機及互動式 QR 碼登入會建立獨立的授權。 警告標題在匯入表單中始終可見;當提供檔案或金鑰/會話字串時,其完整說明會 自動展開。閱讀後可將其收起, 以便在手機上仍能正常使用檔案瀏覽器與連線控制項。

經確認的部署(Phala Cloud、Intel TDX)不會針對 匯入的金鑰進行收集。在此情況下,檔案與授權金鑰僅在選取「建立獨立 授權」時才會建立連結;批量匯入將被拒絕。手機與 QR 碼登入功能則如常運作。

  • 檔案會在您的 TgWitness 伺服器記憶體中進行轉換。上傳的檔案不會被儲存, ZIP 檔案不會解壓縮至磁碟,也不會與任何外部服務進行連線。
  • 隨後會將生成的會話記錄與 Telegram 進行比對。若檔案中載明使用者 ID, 則該 ID 必須與 Telegram 回報的帳戶相符。
  • 描述不同帳戶或不同 API 憑證的檔案將被拒絕 而非僅選擇其中一個。
  • 密碼或會話文字欄位包含 TData 本地密碼欄位,此處可貼上 StringSession 並在未登入的情況下讀取檔案(填寫表單時無需 與 Telegram 連線)。 貼上 StringSession 會清除已選取的檔案,而選擇 檔案則會清除已貼上的文字,因此驗證與連線皆會採用最新的選擇。 變更密碼後,請再次按下「檢查檔案」。

建立獨立的授權機制#

請選擇「在連線前建立獨立授權」並匯入檔案,或 選用「授權金鑰」。TgWitness 會短暫連線至匯入的「捐贈者」,利用其核准 新客戶端的 QR 登入憑證,並在核准後立即斷開與「捐贈者」的連線。 新客戶端擁有專屬的授權金鑰,以及獨立選定的桌面 設定檔。「捐贈者」提供的 API 憑證與裝置設定檔僅用於 與「捐贈者」的連線。現有的授權不會被登出或撤銷。

在此步驟中,請務必將捐贈者的原始客戶端完全關閉。初始 連線仍使用其複製的金鑰,因此此模式無法消除該初始 並行使用風險。一旦建立新的授權連線,擁有者即可重新開啟 原始客戶端,並同時使用兩者。 互動式 QR 碼登入可讓 原始客戶端在無需在此處複製或連接其金鑰的情況下,批准此次登入。

請勿登出或結束捐贈者的會話。當批准 QR 登入的會話結束時,Telegram 也會終止其所批准的會話;在實際測試中,新 授權會在捐贈者登出後一秒內停止。匯入記錄會 記錄捐贈者的會話(session_origin.approved_by:裝置、API ID 及建立時間)。 「會話清單」會標記該會話;「結束會話」會拒絕該會話;而「結束所有其他會話」 及「將此設為唯一會話」則會讓捐贈者保持登入狀態。

若 Telegram 要求進行雙因素驗證 (2FA),此模式會 twoFA 已選取的 JSON 檔案(若存在), 否則會要求輸入密碼。若匯入的密碼遭拒絕,系統將返回密碼輸入表單。 密碼不會被儲存。候選金鑰會以加密形式儲存於 independent_login.enc,包含資料中心遷移期間的變更。發生 中斷後,請選擇相同的來源帳號並選取此選項,以恢復已儲存的候選金鑰。 來源帳號會在 help.getAppConfig 進行驗證;若來源帳戶處於凍結狀態, 則在此處中止。若 Telegram 在批准登入前拒絕該來源帳戶,未獲批准的 候選金鑰將被丟棄,並可重新開始匯入。僅當 Telegram 回報該候選金鑰 尚未登入時,另一來源帳戶才會取代已儲存的候選金鑰;若 候選金鑰已登入或正在等待其雙因素驗證密碼,則會予以保留。 工作區仍會為該帳戶保留;即使完成失敗也不會刪除 新的工作區。請保留其資料目錄和金庫金鑰。最終的憑證及 account.authorized 日誌記錄中將包含匯入方法、輸入格式及 捐贈者 API ID,但不會包含捐贈者的金鑰或密碼。

2026年11月5日,一個專用帳戶通過了 Telethon、Pyrogram 及 TData 捐贈者的即時驗證:2 因素驗證(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 小時之連線的此類請求。 當此工作空間透過 QR 碼從匯入的會話登入時,最初核准該會話的 會話將保持登入狀態: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 缺乏受支援的授權欄位,則僅為元資料。請新增其 會話檔案,或繼續使用手機或 QR 碼登入。若 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 關閉,或透過手機或 QR 碼登入 TgWitness。建議使用 專用帳戶,但這並不能確保複製的金鑰在並行使用時是安全的。

此規則同樣適用於匯入的 .session 檔案、StringSession 文字及 Auth Key HEX。 其他擁有獨立建立之授權的用戶仍可保持登入狀態。 請參閱 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 憑證;您可透過手機或 QR 碼登入,或新增一個會話 檔案。系統不接受批次清單(帳戶的 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 識別碼 + 雜湊值
來自 TDLib 應用程式的 td.binlog 或 db.sqlite TDLib 儲存 不支援
123456789:AA… 機器人代幣 不支援

不支援的格式#

格式 替代版本
TDLib 儲存 (td.binlog) 及 TDLib 匯出功能 透過手機或 QR 碼登入
Pyrogram 會話字串 請使用 Pyrogram .session 檔案,或透過手機/QR 碼
TData 附帶多個已登入的帳戶 請在 Telegram Desktop 中登出其他帳戶,或使用各帳戶專屬的會話檔案
機器人代幣 不支援:TgWitness 僅以使用者帳戶身分進行監測
包含多個帳戶的 CSV/JSON 清單 透過帳戶 → 匯入帳戶匯入受支援的工作階段檔案,或在個別的工作區中透過電話號碼/QR 碼登入
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 此檔案是由非常舊或來源不明的函式庫版本所建立。請改用手機號碼/QR 碼登入。
僅支援經授權的生產環境使用者會話 該 Pyrogram 檔案屬於某個機器人或測試網路。
TData 存檔已超過 512 筆記錄或 32 MiB 僅包含 ZIP 檔案 key_datas 和 D877F783D5D3EF8Cs,而非整個資料夾。
無法解密 TData。請檢查桌面本機密碼 請在「密碼」或「會話文字」欄位中輸入 Telegram Desktop 的本地密碼。
每次僅可匯入一個 TData 帳戶 Telegram Desktop 擁有多個帳戶;請參閱「不支援的格式」。
選定的檔案描述了不同的帳戶或 API 憑證 僅選取單一帳戶的檔案。
JSON 內容中未包含任何受支援的 API 憑證或授權資訊 請檢查 Account JSON 中的欄位名稱。
僅限 API 元資料 該 JSON 檔案未包含會話資訊。請新增 .session 檔案,或使用手機/QR 碼。
授權金鑰的十六進位值必須包含全部 512 個十六進位字元 金鑰已被截斷或包含「…」。
帳號 ID 與匯入的帳號不符 該檔案的用戶 ID 與 Telegram 所顯示的不符;此檔案屬於另一個帳號。
該帳號已屬於另一個工作區 請開啟該工作區,而非重複新增該帳號兩次。
已連線,但「更多工具」→「來源」中的聊天清單缺少一個私人群組 檢查成員資格。揀選器會檢查前1,000個對話;請在「更多工具」→「參數」中提高此限制。
代理連線失敗 請檢查路由與 IP 模式。自動模式 MTProxy 會嘗試其他可用的入口。隱藏位址模式會進行等待;「直接」模式作為最後手段,可在設定的延遲時間過後直接連線。請參閱路由模式說明。

另請參閱:代理伺服器與加密的連線及安全性, 以及登入後資料擷取的運作方式。